@hyperbrowser/sdk 0.84.0 → 0.85.0

package/dist/sandbox/process.js

@@ -0,0 +1,230 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SandboxProcessesApi = exports.SandboxProcessHandle = void 0;
+const DEFAULT_PROCESS_KILL_WAIT_MS = 5000;
+const normalizeProcessSummary = (process) => ({
+    id: process.id,
+    status: process.status,
+    command: process.command,
+    args: process.args,
+    cwd: process.cwd,
+    pid: process.pid,
+    exitCode: process.exit_code,
+    startedAt: process.started_at,
+    completedAt: process.completed_at,
+});
+const normalizeProcessResult = (result) => ({
+    id: result.id,
+    status: result.status,
+    exitCode: result.exit_code,
+    stdout: result.stdout,
+    stderr: result.stderr,
+    startedAt: result.started_at,
+    completedAt: result.completed_at,
+    error: result.error,
+});
+const normalizeResultToSummary = (result) => ({
+    id: result.id,
+    status: result.status,
+    command: "",
+    cwd: "",
+    exitCode: result.exitCode,
+    startedAt: result.startedAt,
+    completedAt: result.completedAt,
+});
+const normalizeStreamEvent = (event) => {
+    if (event.event === "output") {
+        const payload = event.data;
+        return {
+            type: payload.stream,
+            seq: payload.seq,
+            data: payload.data,
+            timestamp: payload.timestamp,
+        };
+    }
+    if (event.event === "done") {
+        return {
+            type: "exit",
+            result: normalizeProcessResult(event.data),
+        };
+    }
+    return null;
+};
+const buildProcessPayload = (input) => ({
+    command: input.command,
+    args: input.args,
+    cwd: input.cwd,
+    env: input.env,
+    timeoutMs: input.timeoutMs,
+    timeout_sec: input.timeoutSec,
+    useShell: input.useShell,
+});
+const encodeStdinPayload = (input) => {
+    if (input.data === undefined) {
+        return {
+            eof: input.eof,
+        };
+    }
+    if (typeof input.data === "string") {
+        return {
+            data: input.data,
+            encoding: input.encoding || "utf8",
+            eof: input.eof,
+        };
+    }
+    return {
+        data: Buffer.from(input.data).toString("base64"),
+        encoding: "base64",
+        eof: input.eof,
+    };
+};
+class SandboxProcessHandle {
+    constructor(transport, summary) {
+        this.transport = transport;
+        this.summary = summary;
+    }
+    get id() {
+        return this.summary.id;
+    }
+    get status() {
+        return this.summary.status;
+    }
+    toJSON() {
+        return { ...this.summary };
+    }
+    async refresh() {
+        const response = await this.transport.requestJSON(`/sandbox/processes/${this.id}`);
+        this.summary = normalizeProcessSummary(response.process);
+        return this;
+    }
+    async wait(params = {}) {
+        const response = await this.transport.requestJSON(`/sandbox/processes/${this.id}/wait`, {
+            method: "POST",
+            body: JSON.stringify({
+                timeoutMs: params.timeoutMs,
+                timeout_sec: params.timeoutSec,
+            }),
+            headers: {
+                "content-type": "application/json",
+            },
+        });
+        const result = normalizeProcessResult(response.result);
+        this.summary = {
+            ...this.summary,
+            ...normalizeResultToSummary(result),
+            command: this.summary.command,
+            args: this.summary.args,
+            cwd: this.summary.cwd,
+            pid: this.summary.pid,
+        };
+        return result;
+    }
+    async signal(signal) {
+        const response = await this.transport.requestJSON(`/sandbox/processes/${this.id}/signal`, {
+            method: "POST",
+            body: JSON.stringify({ signal }),
+            headers: {
+                "content-type": "application/json",
+            },
+        });
+        this.summary = normalizeProcessSummary(response.process);
+    }
+    async kill(params = {}) {
+        const response = await this.transport.requestJSON(`/sandbox/processes/${this.id}`, {
+            method: "DELETE",
+        });
+        this.summary = normalizeProcessSummary(response.process);
+        const waitParams = params.timeoutMs !== undefined
+            ? {
+                timeoutMs: params.timeoutMs,
+                timeoutSec: params.timeoutSec,
+            }
+            : params.timeoutSec !== undefined
+                ? {
+                    timeoutSec: params.timeoutSec,
+                }
+                : {
+                    timeoutMs: DEFAULT_PROCESS_KILL_WAIT_MS,
+                };
+        return this.wait({
+            ...waitParams,
+        });
+    }
+    async writeStdin(input) {
+        const payload = typeof input === "string" || input instanceof Uint8Array
+            ? encodeStdinPayload({ data: input })
+            : encodeStdinPayload(input);
+        await this.transport.requestJSON(`/sandbox/processes/${this.id}/stdin`, {
+            method: "POST",
+            body: JSON.stringify(payload),
+            headers: {
+                "content-type": "application/json",
+            },
+        });
+    }
+    async *stream(fromSeq) {
+        const params = fromSeq && fromSeq > 0
+            ? {
+                from_seq: fromSeq,
+            }
+            : undefined;
+        for await (const event of this.transport.streamSSE(`/sandbox/processes/${this.id}/stream`, params)) {
+            const normalized = normalizeStreamEvent(event);
+            if (normalized) {
+                yield normalized;
+            }
+        }
+    }
+    async result() {
+        return this.wait();
+    }
+}
+exports.SandboxProcessHandle = SandboxProcessHandle;
+class SandboxProcessesApi {
+    constructor(transport) {
+        this.transport = transport;
+    }
+    async exec(input) {
+        const response = await this.transport.requestJSON("/sandbox/exec", {
+            method: "POST",
+            body: JSON.stringify(buildProcessPayload(input)),
+            headers: {
+                "content-type": "application/json",
+            },
+        });
+        return normalizeProcessResult(response.result);
+    }
+    async start(input) {
+        const response = await this.transport.requestJSON("/sandbox/processes", {
+            method: "POST",
+            body: JSON.stringify(buildProcessPayload(input)),
+            headers: {
+                "content-type": "application/json",
+            },
+        });
+        return new SandboxProcessHandle(this.transport, normalizeProcessSummary(response.process));
+    }
+    async get(processId) {
+        const response = await this.transport.requestJSON(`/sandbox/processes/${processId}`);
+        return new SandboxProcessHandle(this.transport, normalizeProcessSummary(response.process));
+    }
+    async list(params = {}) {
+        const status = Array.isArray(params.status)
+            ? params.status.length > 0
+                ? params.status.join(",")
+                : undefined
+            : params.status;
+        const response = await this.transport.requestJSON("/sandbox/processes", undefined, {
+            status,
+            limit: params.limit,
+            cursor: params.cursor,
+            created_after: params.createdAfter,
+            created_before: params.createdBefore,
+        });
+        return {
+            data: response.data.map(normalizeProcessSummary),
+            nextCursor: response.next_cursor || undefined,
+        };
+    }
+}
+exports.SandboxProcessesApi = SandboxProcessesApi;

package/dist/sandbox/terminal.d.ts

@@ -0,0 +1,45 @@
+import WebSocket from "ws";
+import { RuntimeTransport } from "./base";
+import { SandboxTerminalCreateParams, SandboxTerminalEvent, SandboxTerminalKillParams, SandboxTerminalStatus, SandboxTerminalWaitParams } from "../types/sandbox";
+interface RuntimeConnectionInfo {
+    sandboxId: string;
+    baseUrl: string;
+    token: string;
+}
+export declare class SandboxTerminalConnection {
+    private readonly ws;
+    private readonly eventsQueue;
+    constructor(ws: WebSocket);
+    events(): AsyncIterable<SandboxTerminalEvent>;
+    write(data: string | Uint8Array): Promise<void>;
+    resize(rows: number, cols: number): Promise<void>;
+    close(): Promise<void>;
+    private send;
+}
+export declare class SandboxTerminalHandle {
+    private readonly transport;
+    private readonly getConnectionInfo;
+    private status;
+    private readonly runtimeProxyOverride?;
+    constructor(transport: RuntimeTransport, getConnectionInfo: () => Promise<RuntimeConnectionInfo>, status: SandboxTerminalStatus, runtimeProxyOverride?: string | undefined);
+    get id(): string;
+    get current(): SandboxTerminalStatus;
+    toJSON(): SandboxTerminalStatus;
+    refresh(includeOutput?: boolean): Promise<SandboxTerminalHandle>;
+    wait(params?: SandboxTerminalWaitParams): Promise<SandboxTerminalStatus>;
+    signal(signal?: string): Promise<SandboxTerminalStatus>;
+    kill(): Promise<SandboxTerminalStatus>;
+    kill(signal: string): Promise<SandboxTerminalStatus>;
+    kill(params: SandboxTerminalKillParams): Promise<SandboxTerminalStatus>;
+    resize(rows: number, cols: number): Promise<SandboxTerminalStatus>;
+    attach(): Promise<SandboxTerminalConnection>;
+}
+export declare class SandboxTerminalApi {
+    private readonly transport;
+    private readonly getConnectionInfo;
+    private readonly runtimeProxyOverride?;
+    constructor(transport: RuntimeTransport, getConnectionInfo: () => Promise<RuntimeConnectionInfo>, runtimeProxyOverride?: string | undefined);
+    create(params: SandboxTerminalCreateParams): Promise<SandboxTerminalHandle>;
+    get(id: string, includeOutput?: boolean): Promise<SandboxTerminalHandle>;
+}
+export {};

package/dist/sandbox/terminal.js

@@ -0,0 +1,217 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SandboxTerminalApi = exports.SandboxTerminalHandle = exports.SandboxTerminalConnection = void 0;
+const ws_1 = __importDefault(require("ws"));
+const ws_2 = require("./ws");
+const DEFAULT_TERMINAL_KILL_WAIT_MS = 5000;
+const normalizeTerminalOutputChunk = (output) => {
+    const raw = Buffer.from(output.data, "base64");
+    return {
+        seq: output.seq,
+        data: raw.toString("utf8"),
+        raw,
+        timestamp: output.timestamp,
+    };
+};
+const cloneTerminalStatus = (status) => ({
+    ...status,
+    output: status.output?.map((chunk) => ({
+        ...chunk,
+        raw: Buffer.from(chunk.raw),
+    })),
+});
+const normalizeTerminalStatus = (pty) => ({
+    id: pty.id,
+    command: pty.command,
+    args: pty.args,
+    cwd: pty.cwd,
+    pid: pty.pid,
+    running: pty.running,
+    exitCode: pty.exitCode,
+    error: pty.error,
+    timedOut: pty.timedOut,
+    rows: pty.rows,
+    cols: pty.cols,
+    startedAt: pty.startedAt,
+    finishedAt: pty.finishedAt,
+    output: pty.output?.map(normalizeTerminalOutputChunk),
+});
+class SandboxTerminalConnection {
+    constructor(ws) {
+        this.ws = ws;
+        this.eventsQueue = new ws_2.AsyncEventQueue();
+        ws.on("message", (data) => {
+            try {
+                const parsed = JSON.parse(data.toString());
+                if (parsed.type === "output") {
+                    const output = normalizeTerminalOutputChunk(parsed);
+                    this.eventsQueue.push({
+                        type: "output",
+                        ...output,
+                    });
+                    return;
+                }
+                this.eventsQueue.push({
+                    type: "exit",
+                    status: normalizeTerminalStatus(parsed.status),
+                });
+            }
+            catch (error) {
+                this.eventsQueue.fail(error);
+            }
+        });
+        ws.on("close", () => {
+            this.eventsQueue.close();
+        });
+        ws.on("error", (error) => {
+            this.eventsQueue.fail(error);
+        });
+    }
+    events() {
+        return this.eventsQueue;
+    }
+    async write(data) {
+        const payload = typeof data === "string"
+            ? {
+                type: "input",
+                data,
+            }
+            : {
+                type: "input",
+                data: Buffer.from(data).toString("base64"),
+                encoding: "base64",
+            };
+        await this.send(payload);
+    }
+    async resize(rows, cols) {
+        await this.send({
+            type: "resize",
+            rows,
+            cols,
+        });
+    }
+    async close() {
+        if (this.ws.readyState === ws_1.default.CLOSING || this.ws.readyState === ws_1.default.CLOSED) {
+            return;
+        }
+        await new Promise((resolve) => {
+            this.ws.once("close", () => resolve());
+            this.ws.close();
+        });
+    }
+    async send(payload) {
+        await new Promise((resolve, reject) => {
+            this.ws.send(JSON.stringify(payload), (error) => {
+                if (error) {
+                    reject(error);
+                    return;
+                }
+                resolve();
+            });
+        });
+    }
+}
+exports.SandboxTerminalConnection = SandboxTerminalConnection;
+class SandboxTerminalHandle {
+    constructor(transport, getConnectionInfo, status, runtimeProxyOverride) {
+        this.transport = transport;
+        this.getConnectionInfo = getConnectionInfo;
+        this.status = status;
+        this.runtimeProxyOverride = runtimeProxyOverride;
+    }
+    get id() {
+        return this.status.id;
+    }
+    get current() {
+        return cloneTerminalStatus(this.status);
+    }
+    toJSON() {
+        return cloneTerminalStatus(this.status);
+    }
+    async refresh(includeOutput = false) {
+        const response = await this.transport.requestJSON(`/sandbox/pty/${this.id}`, undefined, includeOutput ? { includeOutput: true } : undefined);
+        this.status = normalizeTerminalStatus(response.pty);
+        return this;
+    }
+    async wait(params = {}) {
+        const response = await this.transport.requestJSON(`/sandbox/pty/${this.id}/wait`, {
+            method: "POST",
+            body: JSON.stringify({
+                timeoutMs: params.timeoutMs,
+                includeOutput: params.includeOutput,
+            }),
+            headers: {
+                "content-type": "application/json",
+            },
+        });
+        this.status = normalizeTerminalStatus(response.pty);
+        return this.current;
+    }
+    async signal(signal) {
+        const response = await this.transport.requestJSON(`/sandbox/pty/${this.id}/kill`, {
+            method: "POST",
+            body: JSON.stringify({ signal }),
+            headers: {
+                "content-type": "application/json",
+            },
+        });
+        this.status = normalizeTerminalStatus(response.pty);
+        return this.current;
+    }
+    async kill(input) {
+        const params = typeof input === "string" ? { signal: input } : (input ?? {});
+        await this.signal(params.signal);
+        return this.wait({
+            timeoutMs: params.timeoutMs ?? DEFAULT_TERMINAL_KILL_WAIT_MS,
+        });
+    }
+    async resize(rows, cols) {
+        const response = await this.transport.requestJSON(`/sandbox/pty/${this.id}/resize`, {
+            method: "POST",
+            body: JSON.stringify({ rows, cols }),
+            headers: {
+                "content-type": "application/json",
+            },
+        });
+        this.status = normalizeTerminalStatus(response.pty);
+        return this.current;
+    }
+    async attach() {
+        const connectionInfo = await this.getConnectionInfo();
+        const target = (0, ws_2.toWebSocketUrl)(connectionInfo.baseUrl, `/sandbox/pty/${this.id}/ws?sessionId=${encodeURIComponent(connectionInfo.sandboxId)}`, this.runtimeProxyOverride);
+        const headers = {
+            Authorization: `Bearer ${connectionInfo.token}`,
+        };
+        if (target.hostHeader) {
+            headers.Host = target.hostHeader;
+        }
+        const ws = await (0, ws_2.openRuntimeWebSocket)(target, headers);
+        return new SandboxTerminalConnection(ws);
+    }
+}
+exports.SandboxTerminalHandle = SandboxTerminalHandle;
+class SandboxTerminalApi {
+    constructor(transport, getConnectionInfo, runtimeProxyOverride) {
+        this.transport = transport;
+        this.getConnectionInfo = getConnectionInfo;
+        this.runtimeProxyOverride = runtimeProxyOverride;
+    }
+    async create(params) {
+        const response = await this.transport.requestJSON("/sandbox/pty", {
+            method: "POST",
+            body: JSON.stringify(params),
+            headers: {
+                "content-type": "application/json",
+            },
+        });
+        return new SandboxTerminalHandle(this.transport, this.getConnectionInfo, normalizeTerminalStatus(response.pty), this.runtimeProxyOverride);
+    }
+    async get(id, includeOutput = false) {
+        const response = await this.transport.requestJSON(`/sandbox/pty/${id}`, undefined, includeOutput ? { includeOutput: true } : undefined);
+        return new SandboxTerminalHandle(this.transport, this.getConnectionInfo, normalizeTerminalStatus(response.pty), this.runtimeProxyOverride);
+    }
+}
+exports.SandboxTerminalApi = SandboxTerminalApi;

package/dist/sandbox/ws.d.ts

@@ -0,0 +1,18 @@
+import WebSocket from "ws";
+export declare class AsyncEventQueue<T> implements AsyncIterable<T> {
+    private readonly values;
+    private readonly waiters;
+    private done;
+    private error;
+    push(value: T): void;
+    close(): void;
+    fail(error: unknown): void;
+    [Symbol.asyncIterator](): AsyncIterator<T>;
+}
+export interface RuntimeTransportTarget {
+    url: string;
+    hostHeader?: string;
+}
+export declare const resolveRuntimeTransportTarget: (baseUrl: string, path: string, runtimeProxyOverride?: string) => RuntimeTransportTarget;
+export declare const toWebSocketUrl: (baseUrl: string, path: string, runtimeProxyOverride?: string) => RuntimeTransportTarget;
+export declare const openRuntimeWebSocket: (target: RuntimeTransportTarget, headers: Record<string, string>) => Promise<WebSocket>;

package/dist/sandbox/ws.js

@@ -0,0 +1,188 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.openRuntimeWebSocket = exports.toWebSocketUrl = exports.resolveRuntimeTransportTarget = exports.AsyncEventQueue = void 0;
+const ws_1 = __importDefault(require("ws"));
+const client_1 = require("../client");
+class AsyncEventQueue {
+    constructor() {
+        this.values = [];
+        this.waiters = [];
+        this.done = false;
+        this.error = null;
+    }
+    push(value) {
+        if (this.done) {
+            return;
+        }
+        const waiter = this.waiters.shift();
+        if (waiter) {
+            waiter.resolve({ value, done: false });
+            return;
+        }
+        this.values.push(value);
+    }
+    close() {
+        if (this.done) {
+            return;
+        }
+        this.done = true;
+        while (this.waiters.length > 0) {
+            this.waiters.shift()?.resolve({ value: undefined, done: true });
+        }
+    }
+    fail(error) {
+        if (this.done) {
+            return;
+        }
+        this.done = true;
+        this.error = error;
+        while (this.waiters.length > 0) {
+            this.waiters.shift()?.reject(error);
+        }
+    }
+    [Symbol.asyncIterator]() {
+        return {
+            next: () => {
+                if (this.values.length > 0) {
+                    return Promise.resolve({
+                        value: this.values.shift(),
+                        done: false,
+                    });
+                }
+                if (this.done) {
+                    if (this.error) {
+                        return Promise.reject(this.error);
+                    }
+                    return Promise.resolve({ value: undefined, done: true });
+                }
+                return new Promise((resolve, reject) => {
+                    this.waiters.push({ resolve, reject });
+                });
+            },
+        };
+    }
+}
+exports.AsyncEventQueue = AsyncEventQueue;
+const RETRYABLE_STATUS_CODES = new Set([429, 502, 503, 504]);
+const RETRYABLE_NETWORK_CODES = new Set([
+    "ECONNRESET",
+    "ECONNREFUSED",
+    "EAI_AGAIN",
+    "ETIMEDOUT",
+    "ESOCKETTIMEDOUT",
+]);
+const hasScheme = (value) => /^[a-z][a-z0-9+.-]*:\/\//i.test(value);
+const resolveRuntimeTransportTarget = (baseUrl, path, runtimeProxyOverride) => {
+    const url = new URL(path, baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`);
+    if (!runtimeProxyOverride) {
+        return {
+            url: url.toString(),
+        };
+    }
+    const override = new URL(hasScheme(runtimeProxyOverride)
+        ? runtimeProxyOverride
+        : `${url.protocol}//${runtimeProxyOverride}`);
+    url.protocol = override.protocol;
+    url.username = override.username;
+    url.password = override.password;
+    url.hostname = override.hostname;
+    url.port = override.port || url.port;
+    return {
+        url: url.toString(),
+        hostHeader: new URL(baseUrl).host,
+    };
+};
+exports.resolveRuntimeTransportTarget = resolveRuntimeTransportTarget;
+const toWebSocketUrl = (baseUrl, path, runtimeProxyOverride) => {
+    const target = (0, exports.resolveRuntimeTransportTarget)(baseUrl, path, runtimeProxyOverride);
+    const url = new URL(target.url);
+    if (url.protocol === "https:") {
+        url.protocol = "wss:";
+    }
+    else if (url.protocol === "http:") {
+        url.protocol = "ws:";
+    }
+    return {
+        url: url.toString(),
+        hostHeader: target.hostHeader,
+    };
+};
+exports.toWebSocketUrl = toWebSocketUrl;
+const readIncomingMessageBody = (response) => new Promise((resolve, reject) => {
+    const chunks = [];
+    response.on("data", (chunk) => {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    });
+    response.on("end", () => {
+        resolve(Buffer.concat(chunks).toString("utf8"));
+    });
+    response.on("error", reject);
+});
+const normalizeWebSocketError = (error) => {
+    if (error instanceof client_1.HyperbrowserError) {
+        return error;
+    }
+    const networkError = error;
+    return new client_1.HyperbrowserError(error instanceof Error ? error.message : "Unknown runtime websocket error", {
+        retryable: Boolean(networkError?.code && RETRYABLE_NETWORK_CODES.has(networkError.code)),
+        service: "runtime",
+        cause: error,
+    });
+};
+const buildHandshakeError = async (response) => {
+    const rawText = await readIncomingMessageBody(response);
+    let message = `Runtime websocket request failed: ${response.statusCode ?? 0}`;
+    let code;
+    let details;
+    if (rawText) {
+        try {
+            const parsed = JSON.parse(rawText);
+            details = parsed;
+            code = typeof parsed.code === "string" ? parsed.code : undefined;
+            message = parsed.message || parsed.error || rawText;
+        }
+        catch {
+            details = rawText;
+            message = rawText;
+        }
+    }
+    return new client_1.HyperbrowserError(message, {
+        statusCode: response.statusCode,
+        code,
+        requestId: (typeof response.headers["x-request-id"] === "string"
+            ? response.headers["x-request-id"]
+            : undefined) ||
+            (typeof response.headers["request-id"] === "string"
+                ? response.headers["request-id"]
+                : undefined),
+        retryable: Boolean(response.statusCode && RETRYABLE_STATUS_CODES.has(response.statusCode)),
+        service: "runtime",
+        details,
+    });
+};
+const openRuntimeWebSocket = async (target, headers) => new Promise((resolve, reject) => {
+    let settled = false;
+    const socket = new ws_1.default(target.url, { headers });
+    const rejectOnce = (error) => {
+        if (settled) {
+            return;
+        }
+        settled = true;
+        reject(normalizeWebSocketError(error));
+    };
+    socket.once("open", () => {
+        if (settled) {
+            return;
+        }
+        settled = true;
+        resolve(socket);
+    });
+    socket.once("unexpected-response", (_request, response) => {
+        void buildHandshakeError(response).then(rejectOnce).catch(rejectOnce);
+    });
+    socket.once("error", rejectOnce);
+});
+exports.openRuntimeWebSocket = openRuntimeWebSocket;