@remotehost/sdk 0.1.0

package/dist/sandboxes.js

@@ -0,0 +1,234 @@
+import { SandboxCommands } from "./commands.js";
+import { RemoteHostAPIError, RemoteHostConfigurationError, RemoteHostError, RemoteHostTimeoutError, } from "./errors.js";
+import { SandboxFiles } from "./files.js";
+import { unwrap } from "./internal.js";
+import { SandboxMetricsResource } from "./metrics.js";
+import { SandboxPreviews } from "./previews.js";
+import { abortableDelay, requestSignal } from "./request-options.js";
+export class Sandboxes {
+    api;
+    defaultOrgId;
+    constructor(api, defaultOrgId) {
+        this.api = api;
+        this.defaultOrgId = defaultOrgId;
+    }
+    /** List non-deleted sandboxes visible in an organization. */
+    async list(options = {}) {
+        const { orgId, projectId, endUserId } = options;
+        const data = await unwrap(this.api.GET("/orgs/{orgId}/sandboxes", {
+            params: {
+                path: { orgId: this.requireOrgId(orgId) },
+                query: { projectId, endUserId },
+            },
+            signal: requestSignal(options),
+        }));
+        return data.sandboxes.map((sandbox) => new Sandbox(this.api, sandbox));
+    }
+    /** Create a sandbox, waiting for it to become ready by default. */
+    async create(options) {
+        const { orgId, pollIntervalMs, signal: _signal, timeoutMs: _timeoutMs, waitForReady = true, waitTimeoutMs, ...body } = options;
+        const data = await unwrap(this.api.POST("/orgs/{orgId}/sandboxes", {
+            params: { path: { orgId: this.requireOrgId(orgId) } },
+            body,
+            signal: requestSignal(options),
+        }));
+        const sandbox = new Sandbox(this.api, data.sandbox);
+        return waitForReady
+            ? sandbox.waitUntilReady({
+                pollIntervalMs,
+                signal: options.signal,
+                timeoutMs: waitTimeoutMs,
+            })
+            : sandbox;
+    }
+    /** Retrieve one sandbox by id. */
+    async retrieve(sandboxId, options = {}) {
+        const data = await unwrap(this.api.GET("/sandboxes/{sandboxId}", {
+            params: { path: { sandboxId } },
+            signal: requestSignal(options),
+        }));
+        return new Sandbox(this.api, data.sandbox);
+    }
+    requireOrgId(orgId) {
+        const resolved = orgId ?? this.defaultOrgId;
+        if (!resolved) {
+            throw new RemoteHostConfigurationError("An orgId is required. Pass it to the client or this request.");
+        }
+        return resolved;
+    }
+}
+export class Sandbox {
+    api;
+    #data;
+    commands;
+    files;
+    metrics;
+    previews;
+    constructor(api, data) {
+        this.api = api;
+        this.#data = data;
+        this.commands = new SandboxCommands(api, data.id);
+        this.files = new SandboxFiles(api, data.id);
+        this.metrics = new SandboxMetricsResource(api, data.id);
+        this.previews = new SandboxPreviews(api, data.id);
+    }
+    /** Latest raw API representation. Call refresh() to update it. */
+    get data() {
+        return this.#data;
+    }
+    get id() {
+        return this.#data.id;
+    }
+    get orgId() {
+        return this.#data.org_id;
+    }
+    get projectId() {
+        return this.#data.project_id;
+    }
+    get name() {
+        return this.#data.name;
+    }
+    get status() {
+        return this.#data.status;
+    }
+    /** Release compute while preserving the disk of a persistent sandbox. */
+    async sleep(options = {}) {
+        const data = await unwrap(this.api.POST("/sandboxes/{sandboxId}/sleep", {
+            params: { path: { sandboxId: this.id } },
+            signal: requestSignal(options),
+        }));
+        return this.update(data.sandbox);
+    }
+    /** @deprecated Use sleep(). */
+    async stop(options = {}) {
+        const data = await unwrap(this.api.POST("/sandboxes/{sandboxId}/stop", {
+            params: { path: { sandboxId: this.id } },
+            signal: requestSignal(options),
+        }));
+        return this.update(data.sandbox);
+    }
+    /** Wake a sleeping persistent sandbox. */
+    async wake(options = {}) {
+        const data = await unwrap(this.api.POST("/sandboxes/{sandboxId}/wake", {
+            params: { path: { sandboxId: this.id } },
+            signal: requestSignal(options),
+        }));
+        return this.update(data.sandbox);
+    }
+    /** @deprecated Use wake(). */
+    async resume(options = {}) {
+        const data = await unwrap(this.api.POST("/sandboxes/{sandboxId}/resume", {
+            params: { path: { sandboxId: this.id } },
+            signal: requestSignal(options),
+        }));
+        return this.update(data.sandbox);
+    }
+    /** Renew the sandbox lease. */
+    async renew(options = {}) {
+        const data = await unwrap(this.api.POST("/sandboxes/{sandboxId}/renew", {
+            params: { path: { sandboxId: this.id } },
+            signal: requestSignal(options),
+        }));
+        return this.update(data.sandbox);
+    }
+    /** Permanently destroy the sandbox. */
+    async destroy(options = {}) {
+        const data = await unwrap(this.api.POST("/sandboxes/{sandboxId}/destroy", {
+            params: { path: { sandboxId: this.id } },
+            signal: requestSignal(options),
+        }));
+        return this.update(data.sandbox);
+    }
+    /** Change the requested resource allocation. */
+    async resize(body, options = {}) {
+        const data = await unwrap(this.api.POST("/sandboxes/{sandboxId}/resize", {
+            params: { path: { sandboxId: this.id } },
+            body,
+            signal: requestSignal(options),
+        }));
+        this.update(data.sandbox);
+        return {
+            applied: data.applied,
+            liveResizeError: data.liveResizeError,
+            pendingAllocation: data.pendingAllocation,
+            sandbox: this,
+        };
+    }
+    /** Refresh this resource in place from the API. */
+    async refresh(options = {}) {
+        const data = await unwrap(this.api.GET("/sandboxes/{sandboxId}", {
+            params: { path: { sandboxId: this.id } },
+            signal: requestSignal(options),
+        }));
+        return this.update(data.sandbox);
+    }
+    /**
+     * Poll until the sandbox can accept commands, or throw on failure or timeout.
+     *
+     * "running" is the control plane's view; the agent inside the guest can take
+     * a few more seconds to answer. Readiness is therefore confirmed with a
+     * directory listing through the agent, so the first command after this
+     * resolves does not fail with a 502.
+     */
+    async waitUntilReady(options = {}) {
+        const timeoutMs = options.timeoutMs ?? 5 * 60 * 1000;
+        const pollIntervalMs = options.pollIntervalMs ?? 1_000;
+        const startedAt = Date.now();
+        if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+            throw new TypeError("timeoutMs must be a positive number.");
+        }
+        if (!Number.isFinite(pollIntervalMs) || pollIntervalMs <= 0) {
+            throw new TypeError("pollIntervalMs must be a positive number.");
+        }
+        while (true) {
+            if (this.status === "ready" || this.status === "running") {
+                const remainingMs = timeoutMs - (Date.now() - startedAt);
+                if (await this.agentAnswers({ signal: options.signal, timeoutMs: remainingMs })) {
+                    return this;
+                }
+            }
+            else if (this.status === "error" ||
+                this.status === "deleted" ||
+                this.status === "stopping" ||
+                this.status === "stopped") {
+                // A sandbox that is asleep, or on its way to sleep, will not become
+                // ready on its own; waiting would only run out the clock. Wake it first.
+                throw new RemoteHostError(`Sandbox ${this.id} entered status "${this.status}" while waiting for readiness.`);
+            }
+            const remainingMs = timeoutMs - (Date.now() - startedAt);
+            if (remainingMs <= 0) {
+                throw new RemoteHostTimeoutError(`Sandbox ${this.id} was not ready within ${timeoutMs}ms.`);
+            }
+            await abortableDelay(Math.min(pollIntervalMs, remainingMs), options.signal);
+            await this.refresh({ signal: options.signal, timeoutMs: remainingMs });
+        }
+    }
+    toJSON() {
+        return { ...this.#data };
+    }
+    /**
+     * True once the agent inside the sandbox answers a directory listing. A
+     * 400, 500, or 502 means the guest is still coming up, or has just been
+     * paused, and is worth another poll; any other failure is real.
+     */
+    async agentAnswers(options) {
+        if (options.timeoutMs !== undefined && options.timeoutMs <= 0) {
+            return false;
+        }
+        try {
+            await this.files.list("/code", options);
+            return true;
+        }
+        catch (error) {
+            if (error instanceof RemoteHostAPIError &&
+                (error.status === 400 || error.status === 500 || error.status === 502)) {
+                return false;
+            }
+            throw error;
+        }
+    }
+    update(data) {
+        this.#data = data;
+        return this;
+    }
+}

package/dist/version.d.ts

@@ -0,0 +1,3 @@
+/** The installed SDK version. */
+export declare const VERSION = "0.1.0";
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,iCAAiC;AACjC,eAAO,MAAM,OAAO,UAAU,CAAC"}

package/dist/version.js

@@ -0,0 +1,2 @@
+/** The installed SDK version. */
+export const VERSION = "0.1.0";

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@remotehost/sdk",
+  "version": "0.1.0",
+  "description": "Official TypeScript SDK for RemoteHost",
+  "keywords": [
+    "remotehost",
+    "sandbox",
+    "developer-tools",
+    "coding-agent"
+  ],
+  "homepage": "https://docs.remotehost.ai/docs/sdk",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE.md",
+    "THIRD-PARTY-NOTICES.md"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./openapi": {
+      "types": "./dist/generated/schema.d.ts",
+      "import": "./dist/generated/schema.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "openapi-fetch": "^0.17.0"
+  },
+  "devDependencies": {
+    "openapi-typescript": "^7.13.0",
+    "tsx": "^4.19.2"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/remotehostai/sdk.git"
+  },
+  "bugs": {
+    "url": "https://github.com/remotehostai/sdk/issues"
+  },
+  "scripts": {
+    "build": "pnpm run generate && tsc -p tsconfig.json",
+    "generate": "openapi-typescript ../../apps/api/generated/openapi.json -o src/generated/schema.ts",
+    "lint": "pnpm run typecheck",
+    "smoke:staging": "node scripts/staging-smoke.mjs",
+    "test": "node scripts/test.mjs",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.test.json"
+  }
+}