@remotehost/sdk 0.1.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RemoteHost, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,89 @@
+# RemoteHost TypeScript SDK
+
+The official server-side TypeScript SDK for the RemoteHost API, licensed under MIT.
+
+Source, issues, and contributions: [remotehostai/sdk](https://github.com/remotehostai/sdk).
+
+The low-level request and response types in `src/generated` are generated from
+`apps/api/generated/openapi.json`. The public resource API is maintained by hand
+in the rest of `src`.
+
+## Install
+
+```sh
+npm install @remotehost/sdk
+```
+
+## Usage
+
+```ts
+import RemoteHost from "@remotehost/sdk";
+
+const remotehost = new RemoteHost({
+  apiKey: process.env.REMOTEHOST_API_KEY,
+  orgId: "org_123",
+});
+
+const sandbox = await remotehost.sandboxes.create({
+  projectId: "project_123",
+  agent: "codex",
+});
+
+console.log(sandbox.id, sandbox.status);
+const result = await sandbox.commands.run("pnpm test");
+const source = await sandbox.files.readText("src/index.ts");
+const preview = await sandbox.previews.create({ port: 3000 });
+await sandbox.sleep();
+```
+
+`apiKey` defaults to `REMOTEHOST_API_KEY` in server environments. Browser use
+is rejected by default to prevent accidentally exposing a secret key. Sandbox
+creation waits until the sandbox is running and the agent inside it answers,
+so the first command works; pass `waitForReady: false` to get the
+provisioning response immediately.
+
+API failures throw `RemoteHostAPIError` with `status`, `code` (for example
+`rate_limited` or `limit_reached`), `requestId`, and the response body.
+
+For endpoints without a convenience resource, use the fully typed
+`remotehost.raw` OpenAPI client. Generated `paths`, `operations`, and
+`components` types are available from `@remotehost/sdk/openapi`.
+
+See the [SDK guide](https://docs.remotehost.ai/docs/sdk) for commands, files,
+previews, metrics, lifecycle methods, errors, retries, and cancellation.
+
+## Development
+
+The public repository is a standalone source mirror maintained from RemoteHost's
+monorepo. Clone it to inspect the implementation, run tests, or contribute a fix:
+
+```sh
+git clone https://github.com/remotehostai/sdk.git
+cd sdk
+npm ci
+npm test
+npm run typecheck
+npm run build
+```
+
+The generated API types are checked in, so building does not require access to
+the API server or the monorepo. Do not edit `src/generated/schema.ts` by hand;
+report contract changes in an issue so they can be regenerated upstream.
+
+Public pull requests are welcome. Maintainers integrate changes into the
+monorepo and synchronize them back here. Published versions have matching
+`v<version>` tags and GitHub releases; `main` may contain an unpublished snapshot.
+See [CONTRIBUTING.md](https://github.com/remotehostai/sdk/blob/main/CONTRIBUTING.md).
+
+For development inside the monorepo:
+
+```sh
+pnpm --filter @remotehost/sdk generate
+pnpm --filter @remotehost/sdk test
+pnpm --filter @remotehost/sdk build
+```
+
+## License
+
+[MIT](LICENSE.md). Dependencies retain their own licenses; see
+[THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md).

package/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,51 @@
+# Third-party notices
+
+The SDK uses the following separately licensed open-source dependencies.
+
+## openapi-fetch 0.17.0
+
+MIT License
+
+Copyright (c) 2023 Drew Powers
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+## openapi-typescript-helpers 0.1.0
+
+MIT License
+
+Copyright (c) 2023 Drew Powers
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/client.d.ts

@@ -0,0 +1,29 @@
+import type { APIClient } from "./internal.js";
+import { Sandboxes } from "./sandboxes.js";
+export type RemoteHostOptions = {
+    /** Secret API key. Defaults to REMOTEHOST_API_KEY outside browsers. */
+    apiKey?: string;
+    /** API root, including `/v1`. */
+    baseURL?: string;
+    /** Default organization for organization-scoped operations. */
+    orgId?: string;
+    /** Custom Fetch implementation, useful for tests and non-Node runtimes. */
+    fetch?: (request: Request) => Promise<Response>;
+    /** Headers included with every request. Authorization and SDK version are managed by the SDK. */
+    headers?: HeadersInit;
+    /** Maximum automatic retries for safe GET and HEAD requests. Defaults to 2. */
+    maxRetries?: number;
+    /** Default deadline for one HTTP request. Defaults to 10 minutes. */
+    timeoutMs?: number;
+    /** Allow secret-key use in a browser. This can expose the key to users. */
+    dangerouslyAllowBrowser?: boolean;
+};
+/** Server-side client for the RemoteHost API. */
+export declare class RemoteHost {
+    /** Fully typed access to every operation in the generated OpenAPI contract. */
+    readonly raw: APIClient;
+    /** Create, list, and retrieve sandboxes. */
+    readonly sandboxes: Sandboxes;
+    constructor(options?: RemoteHostOptions);
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAO3C,MAAM,MAAM,iBAAiB,GAAG;IAC9B,uEAAuE;IACvE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iCAAiC;IACjC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+DAA+D;IAC/D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2EAA2E;IAC3E,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;IAChD,iGAAiG;IACjG,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,+EAA+E;IAC/E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qEAAqE;IACrE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2EAA2E;IAC3E,uBAAuB,CAAC,EAAE,OAAO,CAAC;CACnC,CAAC;AAEF,iDAAiD;AACjD,qBAAa,UAAU;IACrB,+EAA+E;IAC/E,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAC;IACxB,4CAA4C;IAC5C,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;gBAElB,OAAO,GAAE,iBAAsB;CAuC5C"}

package/dist/client.js

@@ -0,0 +1,121 @@
+import createClient from "openapi-fetch";
+import { RemoteHostConfigurationError } from "./errors.js";
+import { Sandboxes } from "./sandboxes.js";
+import { VERSION } from "./version.js";
+const DEFAULT_BASE_URL = "https://api.remotehost.ai/v1";
+const DEFAULT_TIMEOUT_MS = 10 * 60 * 1000;
+const DEFAULT_MAX_RETRIES = 2;
+/** Server-side client for the RemoteHost API. */
+export class RemoteHost {
+    /** Fully typed access to every operation in the generated OpenAPI contract. */
+    raw;
+    /** Create, list, and retrieve sandboxes. */
+    sandboxes;
+    constructor(options = {}) {
+        if (isBrowser() && !options.dangerouslyAllowBrowser) {
+            throw new RemoteHostConfigurationError("RemoteHost API keys must not be exposed in browser code. Use a server environment, or explicitly set dangerouslyAllowBrowser if you understand the risk.");
+        }
+        const apiKey = options.apiKey ?? readEnvironmentVariable("REMOTEHOST_API_KEY");
+        if (!apiKey) {
+            throw new RemoteHostConfigurationError("Missing API key. Pass apiKey or set REMOTEHOST_API_KEY.");
+        }
+        const headers = new Headers(options.headers);
+        headers.set("authorization", `Bearer ${apiKey}`);
+        headers.set("x-remotehost-sdk-version", VERSION);
+        const fetcher = options.fetch ?? globalThis.fetch;
+        const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        const maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+        if (!Number.isInteger(maxRetries) || maxRetries < 0) {
+            throw new RemoteHostConfigurationError("maxRetries must be a non-negative integer.");
+        }
+        if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+            throw new RemoteHostConfigurationError("timeoutMs must be a positive number.");
+        }
+        const api = createClient({
+            baseUrl: trimTrailingSlash(options.baseURL ?? DEFAULT_BASE_URL),
+            fetch: createReliableFetch(fetcher, { maxRetries, timeoutMs }),
+            headers,
+        });
+        this.raw = api;
+        this.sandboxes = new Sandboxes(api, options.orgId);
+    }
+}
+function isBrowser() {
+    return typeof window !== "undefined" && typeof window.document !== "undefined";
+}
+function readEnvironmentVariable(name) {
+    const runtime = globalThis;
+    return runtime.process?.env?.[name];
+}
+function trimTrailingSlash(url) {
+    return url.replace(/\/+$/, "");
+}
+function createReliableFetch(fetcher, options) {
+    return async (request) => {
+        const retryable = request.method === "GET" || request.method === "HEAD";
+        let attempt = 0;
+        while (true) {
+            const timeout = AbortSignal.timeout(options.timeoutMs);
+            const signal = AbortSignal.any([request.signal, timeout]);
+            try {
+                const response = await fetcher(new Request(request, { signal }));
+                if (!retryable || attempt >= options.maxRetries || !isRetryableStatus(response.status)) {
+                    return response;
+                }
+                await response.body?.cancel().catch(() => undefined);
+                await delay(retryDelayMs(response, attempt), request.signal);
+            }
+            catch (error) {
+                if (request.signal.aborted || errorName(error) === "TimeoutError") {
+                    throw error;
+                }
+                if (!retryable || attempt >= options.maxRetries) {
+                    throw error;
+                }
+                await delay(backoffMs(attempt), request.signal);
+            }
+            attempt += 1;
+        }
+    };
+}
+function isRetryableStatus(status) {
+    return status === 408 || status === 409 || status === 429 || status >= 500;
+}
+function retryDelayMs(response, attempt) {
+    const retryAfter = response.headers.get("retry-after");
+    if (retryAfter) {
+        const seconds = Number(retryAfter);
+        if (Number.isFinite(seconds) && seconds >= 0) {
+            return Math.min(seconds * 1000, 60_000);
+        }
+        const date = Date.parse(retryAfter);
+        if (Number.isFinite(date)) {
+            return Math.min(Math.max(date - Date.now(), 0), 60_000);
+        }
+    }
+    return backoffMs(attempt);
+}
+function backoffMs(attempt) {
+    const exponential = Math.min(500 * 2 ** attempt, 8_000);
+    return Math.round(exponential * (0.75 + Math.random() * 0.5));
+}
+async function delay(ms, signal) {
+    await new Promise((resolve, reject) => {
+        if (signal.aborted) {
+            reject(signal.reason);
+            return;
+        }
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(signal.reason);
+        };
+        const timer = setTimeout(() => {
+            signal.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
+}
+function errorName(error) {
+    return error instanceof Error ? error.name : null;
+}

package/dist/commands.d.ts

@@ -0,0 +1,15 @@
+import type { components } from "./generated/schema.js";
+import type { APIClient } from "./internal.js";
+import type { RequestOptions } from "./request-options.js";
+export type CommandResult = components["schemas"]["ExecSandboxResult"];
+export type RunCommandOptions = RequestOptions & {
+    timeoutSeconds?: number;
+};
+export declare class SandboxCommands {
+    private readonly api;
+    private readonly sandboxId;
+    constructor(api: APIClient, sandboxId: string);
+    /** Run a non-interactive command to completion and capture its exit code and output. */
+    run(command: string, options?: RunCommandOptions): Promise<CommandResult>;
+}
+//# sourceMappingURL=commands.d.ts.map

package/dist/commands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../src/commands.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAE/C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAG3D,MAAM,MAAM,aAAa,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,mBAAmB,CAAC,CAAC;AAEvE,MAAM,MAAM,iBAAiB,GAAG,cAAc,GAAG;IAC/C,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF,qBAAa,eAAe;IAExB,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,SAAS;gBADT,GAAG,EAAE,SAAS,EACd,SAAS,EAAE,MAAM;IAGpC,wFAAwF;IAClF,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,iBAAsB,GAAG,OAAO,CAAC,aAAa,CAAC;CAUpF"}

package/dist/commands.js

@@ -0,0 +1,19 @@
+import { unwrap } from "./internal.js";
+import { requestSignal } from "./request-options.js";
+export class SandboxCommands {
+    api;
+    sandboxId;
+    constructor(api, sandboxId) {
+        this.api = api;
+        this.sandboxId = sandboxId;
+    }
+    /** Run a non-interactive command to completion and capture its exit code and output. */
+    async run(command, options = {}) {
+        const { timeoutSeconds } = options;
+        return unwrap(this.api.POST("/sandboxes/{sandboxId}/exec", {
+            params: { path: { sandboxId: this.sandboxId } },
+            body: { command, timeoutSeconds },
+            signal: requestSignal(options),
+        }));
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,25 @@
+export declare class RemoteHostError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+export declare class RemoteHostConfigurationError extends RemoteHostError {
+    constructor(message: string);
+}
+export declare class RemoteHostConnectionError extends RemoteHostError {
+    constructor(message: string, options?: ErrorOptions);
+}
+export declare class RemoteHostTimeoutError extends RemoteHostConnectionError {
+    constructor(message?: string, options?: ErrorOptions);
+}
+export declare class RemoteHostAPIError extends RemoteHostError {
+    readonly status: number;
+    /**
+     * Machine-readable reason when the API sets one, for example `rate_limited`,
+     * `limit_reached`, `plan_required`, or `snapshot_in_progress`. Null otherwise.
+     */
+    readonly code: string | null;
+    readonly requestId: string | null;
+    readonly headers: Headers;
+    readonly body: unknown;
+    constructor(response: Response, body: unknown);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,qBAAa,eAAgB,SAAQ,KAAK;gBAC5B,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;CAIpD;AAED,qBAAa,4BAA6B,SAAQ,eAAe;gBACnD,OAAO,EAAE,MAAM;CAI5B;AAED,qBAAa,yBAA0B,SAAQ,eAAe;gBAChD,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;CAIpD;AAED,qBAAa,sBAAuB,SAAQ,yBAAyB;gBACvD,OAAO,SAA0C,EAAE,OAAO,CAAC,EAAE,YAAY;CAItF;AAED,qBAAa,kBAAmB,SAAQ,eAAe;IACrD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;gBAEX,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,OAAO;CAS9C"}

package/dist/errors.js

@@ -0,0 +1,77 @@
+export class RemoteHostError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "RemoteHostError";
+    }
+}
+export class RemoteHostConfigurationError extends RemoteHostError {
+    constructor(message) {
+        super(message);
+        this.name = "RemoteHostConfigurationError";
+    }
+}
+export class RemoteHostConnectionError extends RemoteHostError {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "RemoteHostConnectionError";
+    }
+}
+export class RemoteHostTimeoutError extends RemoteHostConnectionError {
+    constructor(message = "The RemoteHost API request timed out.", options) {
+        super(message, options);
+        this.name = "RemoteHostTimeoutError";
+    }
+}
+export class RemoteHostAPIError extends RemoteHostError {
+    status;
+    /**
+     * Machine-readable reason when the API sets one, for example `rate_limited`,
+     * `limit_reached`, `plan_required`, or `snapshot_in_progress`. Null otherwise.
+     */
+    code;
+    requestId;
+    headers;
+    body;
+    constructor(response, body) {
+        super(readErrorMessage(body) ?? `${response.status} ${response.statusText}`.trim());
+        this.name = "RemoteHostAPIError";
+        this.status = response.status;
+        this.code = readErrorCode(body);
+        this.requestId = response.headers.get("x-request-id");
+        this.headers = response.headers;
+        this.body = body;
+    }
+}
+function readErrorCode(body) {
+    if (body &&
+        typeof body === "object" &&
+        "error" in body &&
+        body.error &&
+        typeof body.error === "object" &&
+        "code" in body.error &&
+        typeof body.error.code === "string") {
+        return body.error.code;
+    }
+    return null;
+}
+function readErrorMessage(body) {
+    if (!body || typeof body !== "object") {
+        return null;
+    }
+    if ("error" in body) {
+        const error = body.error;
+        if (typeof error === "string") {
+            return error;
+        }
+        if (error &&
+            typeof error === "object" &&
+            "message" in error &&
+            typeof error.message === "string") {
+            return error.message;
+        }
+    }
+    if ("message" in body && typeof body.message === "string") {
+        return body.message;
+    }
+    return null;
+}

package/dist/files.d.ts

@@ -0,0 +1,36 @@
+import type { components } from "./generated/schema.js";
+import type { APIClient } from "./internal.js";
+import type { RequestOptions } from "./request-options.js";
+export type FilesystemEntry = components["schemas"]["FilesystemEntry"];
+export type FileEncoding = "utf8" | "base64";
+export type ListFilesResult = {
+    path: string;
+    truncated: boolean;
+    entries: FilesystemEntry[];
+};
+export type ReadFileResult = {
+    path: string;
+    content: string;
+    encoding: FileEncoding;
+    size: number;
+};
+export type WriteFileResult = {
+    path: string;
+    size: number;
+};
+export declare class SandboxFiles {
+    private readonly api;
+    private readonly sandboxId;
+    constructor(api: APIClient, sandboxId: string);
+    /** List direct children of a directory. Relative paths resolve beneath `/code`. */
+    list(path?: string, options?: RequestOptions): Promise<ListFilesResult>;
+    /** Read a file with its transport encoding preserved. */
+    read(path: string, options?: RequestOptions): Promise<ReadFileResult>;
+    /** Read a UTF-8 file, decoding a base64 response when necessary. */
+    readText(path: string, options?: RequestOptions): Promise<string>;
+    /** Read a file as bytes. */
+    readBytes(path: string, options?: RequestOptions): Promise<Uint8Array>;
+    /** Write UTF-8 text or binary bytes. Individual writes are limited to 2 MiB. */
+    write(path: string, content: string | Uint8Array, options?: RequestOptions): Promise<WriteFileResult>;
+}
+//# sourceMappingURL=files.d.ts.map

package/dist/files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"files.d.ts","sourceRoot":"","sources":["../src/files.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAE/C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAG3D,MAAM,MAAM,eAAe,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC,iBAAiB,CAAC,CAAC;AACvE,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,QAAQ,CAAC;AAE7C,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,EAAE,eAAe,EAAE,CAAC;CAC5B,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,YAAY,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,qBAAa,YAAY;IAErB,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,SAAS;gBADT,GAAG,EAAE,SAAS,EACd,SAAS,EAAE,MAAM;IAGpC,mFAAmF;IACnF,IAAI,CAAC,IAAI,SAAU,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,eAAe,CAAC;IAS5E,yDAAyD;IACzD,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,cAAc,CAAC;IASzE,oEAAoE;IAC9D,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,MAAM,CAAC;IAO3E,4BAA4B;IACtB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,UAAU,CAAC;IAOhF,gFAAgF;IAChF,KAAK,CACH,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,GAAG,UAAU,EAC5B,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,eAAe,CAAC;CAc5B"}

package/dist/files.js

@@ -0,0 +1,61 @@
+import { unwrap } from "./internal.js";
+import { requestSignal } from "./request-options.js";
+export class SandboxFiles {
+    api;
+    sandboxId;
+    constructor(api, sandboxId) {
+        this.api = api;
+        this.sandboxId = sandboxId;
+    }
+    /** List direct children of a directory. Relative paths resolve beneath `/code`. */
+    list(path = "/code", options = {}) {
+        return unwrap(this.api.GET("/sandboxes/{sandboxId}/files", {
+            params: { path: { sandboxId: this.sandboxId }, query: { path } },
+            signal: requestSignal(options),
+        }));
+    }
+    /** Read a file with its transport encoding preserved. */
+    read(path, options = {}) {
+        return unwrap(this.api.GET("/sandboxes/{sandboxId}/file", {
+            params: { path: { sandboxId: this.sandboxId }, query: { path } },
+            signal: requestSignal(options),
+        }));
+    }
+    /** Read a UTF-8 file, decoding a base64 response when necessary. */
+    async readText(path, options = {}) {
+        const file = await this.read(path, options);
+        return file.encoding === "base64"
+            ? new TextDecoder().decode(base64ToBytes(file.content))
+            : file.content;
+    }
+    /** Read a file as bytes. */
+    async readBytes(path, options = {}) {
+        const file = await this.read(path, options);
+        return file.encoding === "base64"
+            ? base64ToBytes(file.content)
+            : new TextEncoder().encode(file.content);
+    }
+    /** Write UTF-8 text or binary bytes. Individual writes are limited to 2 MiB. */
+    write(path, content, options = {}) {
+        const body = typeof content === "string"
+            ? { path, content, encoding: "utf8" }
+            : { path, content: bytesToBase64(content), encoding: "base64" };
+        return unwrap(this.api.PUT("/sandboxes/{sandboxId}/file", {
+            params: { path: { sandboxId: this.sandboxId } },
+            body,
+            signal: requestSignal(options),
+        }));
+    }
+}
+function base64ToBytes(value) {
+    const binary = atob(value);
+    return Uint8Array.from(binary, (character) => character.charCodeAt(0));
+}
+function bytesToBase64(value) {
+    const chunkSize = 0x8000;
+    let binary = "";
+    for (let offset = 0; offset < value.length; offset += chunkSize) {
+        binary += String.fromCharCode(...value.subarray(offset, offset + chunkSize));
+    }
+    return btoa(binary);
+}