@sapiom/sandbox 0.6.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @sapiom/sandbox
 
+## 0.8.0
+
+### Minor Changes
+
+- 2781e03: Add multipart file upload support. New `uploadFile(path, content, opts?)` handles the full initiate → parallel part uploads → complete lifecycle with per-part retries (408/425/429/5xx + network errors, honors `Retry-After`) and auto-abort on failure. Accepts `Blob | Uint8Array | string`. Low-level `initiateMultipartUpload` / `uploadPart` / `completeMultipartUpload` / `abortMultipartUpload` / `listMultipartParts` primitives are exposed for resumable or custom-retry use cases, and a typed `SandboxHttpError` carries `status` + `retryAfterMs` for programmatic handling.
+
+## 0.7.0
+
+### Minor Changes
+
+- 0f8d6cd: support keepAlive and processTimeout opts
+
 ## 0.6.0
 
 ### Minor Changes

package/README.md

@@ -75,6 +75,80 @@ Writes a file relative to the sandbox's workspace root.
 await sandbox.writeFile("src/index.ts", 'console.log("hi")');
 ```
 
+### `sandbox.uploadFile(path, content, opts?)`
+
+Uploads a file using multipart upload. Handles the full `initiate → upload parts → complete` lifecycle, with parallel part uploads and automatic abort on any failure. Prefer this over `writeFile` for binary content or files over a few MB.
+
+```typescript
+import { openAsBlob } from "node:fs";
+
+// From a buffer / Uint8Array
+await sandbox.uploadFile("data/snapshot.bin", new Uint8Array(bytes));
+
+// From a file on disk without slurping it into memory (Node 20+)
+const blob = await openAsBlob("./huge.parquet");
+await sandbox.uploadFile("datasets/huge.parquet", blob, {
+  partSize: 5 * 1024 * 1024,
+  concurrency: 4,
+  onPartUploaded: (part, progress) => {
+    const pct = ((progress.bytesUploaded / progress.totalBytes) * 100).toFixed(1);
+    console.log(`part ${part.partNumber} ok — ${pct}%`);
+  },
+});
+
+// Cancel a running upload — the server-side multipart session is auto-aborted
+const ctrl = new AbortController();
+setTimeout(() => ctrl.abort(), 10_000);
+await sandbox.uploadFile("big.bin", blob, { signal: ctrl.signal });
+```
+
+**Options:**
+
+| Option            | Type                    | Default         | Description                                                                 |
+|-------------------|-------------------------|-----------------|-----------------------------------------------------------------------------|
+| `partSize`          | `number`                | `5 * 1024 * 1024` | Part size in bytes. The Sapiom ingress rejects uploads over ~8 MiB, so keep this ≤ 7 MiB. |
+| `concurrency`       | `number`                | `4`               | Number of parallel part uploads. Blaxel recommends 3–5.                     |
+| `permissions`       | `string`                | `"0644"`          | Unix file permissions.                                                       |
+| `maxRetries`        | `number`                | `3`               | Retries per failed part on 408/425/429/5xx and network errors. `0` disables.  |
+| `retryBaseDelayMs`  | `number`                | `50`              | Initial backoff in ms. Doubles per attempt with jitter; honors `Retry-After`. |
+| `signal`            | `AbortSignal`           | —                 | Cancel the upload. Triggers an auto-abort of the server-side session.         |
+| `onPartUploaded`    | `(part, progress) => void` | —              | Fired after each part finishes (completion order — not `partNumber` order).   |
+
+The server accepts at most **10,000 parts per upload**. If `content.size / partSize > 10_000`, `uploadFile` throws before making any request and suggests a larger `partSize`.
+
+### Low-level multipart API
+
+For resumable uploads or custom retry logic, drive the multipart lifecycle directly:
+
+```typescript
+const { uploadId } = await sandbox.initiateMultipartUpload("large.bin");
+
+try {
+  // ...upload parts as bytes become available
+  const part1 = await sandbox.uploadPart(uploadId, 1, chunk1);
+  const part2 = await sandbox.uploadPart(uploadId, 2, chunk2);
+
+  // Inspect server-side state (useful after a crash/reconnect)
+  const uploaded = await sandbox.listMultipartParts(uploadId);
+
+  await sandbox.completeMultipartUpload(uploadId, [
+    { partNumber: part1.partNumber, etag: part1.etag },
+    { partNumber: part2.partNumber, etag: part2.etag },
+  ]);
+} catch (err) {
+  await sandbox.abortMultipartUpload(uploadId);
+  throw err;
+}
+```
+
+| Method                                               | Description                                 |
+|------------------------------------------------------|---------------------------------------------|
+| `initiateMultipartUpload(path, opts?)`               | Start a session. Returns `{ uploadId, path }`. |
+| `uploadPart(uploadId, partNumber, bytes, opts?)`     | Upload one part (1-indexed, 1–10000).        |
+| `listMultipartParts(uploadId, opts?)`                | List parts already uploaded.                 |
+| `completeMultipartUpload(uploadId, parts, opts?)`    | Commit the upload.                           |
+| `abortMultipartUpload(uploadId, opts?)`              | Discard the session and clean up parts.      |
+
 ### `sandbox.readFile(path)`
 
 Reads a file relative to the sandbox's workspace root and returns its content as a string.

package/dist/cjs/index.d.ts

@@ -1,3 +1,4 @@
 export { SapiomSandbox } from "./sandbox.js";
-export type { SandboxCreateOptions, SandboxCreateResponse, SandboxTier, PortSpec, ExecOptions, ExecStreamOptions, ExecResult, StreamingExecResult, OutputLine, ProcessCreateResponse, ProcessStatusResponse, } from "./types.js";
+export { SandboxHttpError } from "./multipart.js";
+export type { SandboxCreateOptions, SandboxCreateResponse, SandboxTier, PortSpec, ExecOptions, ExecStreamOptions, ExecResult, StreamingExecResult, OutputLine, ProcessCreateResponse, ProcessStatusResponse, MultipartInitiateResponse, MultipartUploadedPart, MultipartPartInfo, UploadFileOptions, UploadProgress, } from "./types.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/cjs/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,YAAY,EACV,oBAAoB,EACpB,qBAAqB,EACrB,WAAW,EACX,QAAQ,EACR,WAAW,EACX,iBAAiB,EACjB,UAAU,EACV,mBAAmB,EACnB,UAAU,EACV,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClD,YAAY,EACV,oBAAoB,EACpB,qBAAqB,EACrB,WAAW,EACX,QAAQ,EACR,WAAW,EACX,iBAAiB,EACjB,UAAU,EACV,mBAAmB,EACnB,UAAU,EACV,qBAAqB,EACrB,qBAAqB,EACrB,yBAAyB,EACzB,qBAAqB,EACrB,iBAAiB,EACjB,iBAAiB,EACjB,cAAc,GACf,MAAM,YAAY,CAAC"}

package/dist/cjs/index.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SapiomSandbox = void 0;
+exports.SandboxHttpError = exports.SapiomSandbox = void 0;
 var sandbox_js_1 = require("./sandbox.js");
 Object.defineProperty(exports, "SapiomSandbox", { enumerable: true, get: function () { return sandbox_js_1.SapiomSandbox; } });
+var multipart_js_1 = require("./multipart.js");
+Object.defineProperty(exports, "SandboxHttpError", { enumerable: true, get: function () { return multipart_js_1.SandboxHttpError; } });
 //# sourceMappingURL=index.js.map

package/dist/cjs/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;AAAA,2CAA6C;AAApC,2GAAA,aAAa,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;AAAA,2CAA6C;AAApC,2GAAA,aAAa,OAAA;AACtB,+CAAkD;AAAzC,gHAAA,gBAAgB,OAAA"}

package/dist/cjs/multipart.d.ts

@@ -0,0 +1,75 @@
+/** Max parts allowed per multipart upload (Blaxel constraint). */
+export declare const MAX_PARTS = 10000;
+/** Default number of retries for a single failed part upload. */
+export declare const DEFAULT_MAX_RETRIES = 3;
+/** Default initial retry backoff in milliseconds. */
+export declare const DEFAULT_RETRY_BASE_DELAY_MS = 50;
+/**
+ * Error thrown by multipart HTTP methods when the server returns a non-2xx.
+ * Exposes `status` + `retryAfterMs` (parsed from `Retry-After`) so callers
+ * and the retry loop can make informed decisions.
+ */
+export declare class SandboxHttpError extends Error {
+    readonly status: number;
+    readonly retryAfterMs?: number;
+    constructor(message: string, status: number, retryAfterMs?: number);
+}
+/**
+ * Parse a `Retry-After` header value. Supports both forms:
+ *  - delta-seconds integer (e.g. `"30"`)
+ *  - HTTP-date (e.g. `"Wed, 21 Oct 2015 07:28:00 GMT"`)
+ */
+export declare function parseRetryAfter(header: string | null): number | undefined;
+/**
+ * Wrap a `fetch` response: if non-2xx, throw a `SandboxHttpError` carrying
+ * the status + Retry-After, otherwise return the response for the caller to
+ * parse.
+ */
+export declare function ensureOk(response: Response, errorPrefix: string): Promise<Response>;
+export interface RetryOptions {
+    /** Max number of retry attempts after the initial try. @default 3 */
+    maxRetries?: number;
+    /** Initial backoff in ms. Doubles each retry with up to `base` ms jitter. @default 50 */
+    retryBaseDelayMs?: number;
+    /** AbortSignal to cancel the retry loop. */
+    signal?: AbortSignal;
+}
+/**
+ * Retry `fn` up to `maxRetries` times on retryable errors with jittered
+ * exponential backoff. Honors `Retry-After` when the server provides one.
+ * Respects `signal` for prompt cancellation during the backoff wait.
+ */
+export declare function withRetry<T>(fn: (attempt: number) => Promise<T>, opts?: RetryOptions): Promise<T>;
+/**
+ * Default part size: 5 MiB. Bottom of Blaxel's recommended 5–10 MB range
+ * and well clear of the Sapiom ingress 8 MiB body-size ceiling (with
+ * room left for multipart form-data overhead).
+ */
+export declare const DEFAULT_PART_SIZE: number;
+/** Default number of parallel part uploads. */
+export declare const DEFAULT_CONCURRENCY = 4;
+/** Default file permissions (Blaxel default). */
+export declare const DEFAULT_PERMISSIONS = "0644";
+/**
+ * Normalize any supported content type into a `Blob`.
+ * `Blob.slice()` gives us random-access + lazy reads, so large inputs don't
+ * have to sit materialized in memory.
+ */
+export declare function toBlob(content: Blob | Uint8Array | string): Blob;
+export interface PartPlan {
+    partNumber: number;
+    start: number;
+    end: number;
+}
+/**
+ * Split a byte range into part plans.
+ * Always emits at least one part (even for zero-byte inputs) so the caller
+ * still goes through the initiate/upload/complete handshake.
+ */
+export declare function planParts(totalBytes: number, partSize: number): PartPlan[];
+/**
+ * Run `worker` over `items` with at most `concurrency` promises in flight.
+ * Rejects on the first worker failure (and stops scheduling further items).
+ */
+export declare function runWithConcurrency<T, R>(items: readonly T[], concurrency: number, worker: (item: T, index: number) => Promise<R>): Promise<R[]>;
+//# sourceMappingURL=multipart.d.ts.map

package/dist/cjs/multipart.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"multipart.d.ts","sourceRoot":"","sources":["../../src/multipart.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,eAAO,MAAM,SAAS,QAAS,CAAC;AAEhC,iEAAiE;AACjE,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAErC,qDAAqD;AACrD,eAAO,MAAM,2BAA2B,KAAK,CAAC;AAK9C;;;;GAIG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;gBAEnB,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM;CAMnE;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,SAAS,CAOzE;AAED;;;;GAIG;AACH,wBAAsB,QAAQ,CAC5B,QAAQ,EAAE,QAAQ,EAClB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,QAAQ,CAAC,CASnB;AAED,MAAM,WAAW,YAAY;IAC3B,qEAAqE;IACrE,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,yFAAyF;IACzF,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B,4CAA4C;IAC5C,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAcD;;;;GAIG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAC/B,EAAE,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,EACnC,IAAI,CAAC,EAAE,YAAY,GAClB,OAAO,CAAC,CAAC,CAAC,CAmBZ;AAoBD;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,QAAkB,CAAC;AAEjD,+CAA+C;AAC/C,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAErC,iDAAiD;AACjD,eAAO,MAAM,mBAAmB,SAAS,CAAC;AAE1C;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,OAAO,EAAE,IAAI,GAAG,UAAU,GAAG,MAAM,GAAG,IAAI,CAMhE;AAED,MAAM,WAAW,QAAQ;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,QAAQ,EAAE,CAsB1E;AAED;;;GAGG;AACH,wBAAsB,kBAAkB,CAAC,CAAC,EAAE,CAAC,EAC3C,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GAC7C,OAAO,CAAC,CAAC,EAAE,CAAC,CAqCd"}

package/dist/cjs/multipart.js

@@ -0,0 +1,199 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_PERMISSIONS = exports.DEFAULT_CONCURRENCY = exports.DEFAULT_PART_SIZE = exports.SandboxHttpError = exports.DEFAULT_RETRY_BASE_DELAY_MS = exports.DEFAULT_MAX_RETRIES = exports.MAX_PARTS = void 0;
+exports.parseRetryAfter = parseRetryAfter;
+exports.ensureOk = ensureOk;
+exports.withRetry = withRetry;
+exports.toBlob = toBlob;
+exports.planParts = planParts;
+exports.runWithConcurrency = runWithConcurrency;
+/** Max parts allowed per multipart upload (Blaxel constraint). */
+exports.MAX_PARTS = 10000;
+/** Default number of retries for a single failed part upload. */
+exports.DEFAULT_MAX_RETRIES = 3;
+/** Default initial retry backoff in milliseconds. */
+exports.DEFAULT_RETRY_BASE_DELAY_MS = 50;
+/** HTTP status codes worth retrying. 4xx are user errors unless explicitly transient. */
+const RETRYABLE_STATUS = new Set([408, 425, 429, 500, 502, 503, 504]);
+/**
+ * Error thrown by multipart HTTP methods when the server returns a non-2xx.
+ * Exposes `status` + `retryAfterMs` (parsed from `Retry-After`) so callers
+ * and the retry loop can make informed decisions.
+ */
+class SandboxHttpError extends Error {
+    constructor(message, status, retryAfterMs) {
+        super(message);
+        this.name = "SandboxHttpError";
+        this.status = status;
+        if (retryAfterMs !== undefined)
+            this.retryAfterMs = retryAfterMs;
+    }
+}
+exports.SandboxHttpError = SandboxHttpError;
+/**
+ * Parse a `Retry-After` header value. Supports both forms:
+ *  - delta-seconds integer (e.g. `"30"`)
+ *  - HTTP-date (e.g. `"Wed, 21 Oct 2015 07:28:00 GMT"`)
+ */
+function parseRetryAfter(header) {
+    if (!header)
+        return undefined;
+    const seconds = Number(header);
+    if (Number.isFinite(seconds) && seconds >= 0)
+        return seconds * 1000;
+    const date = Date.parse(header);
+    if (!Number.isNaN(date))
+        return Math.max(0, date - Date.now());
+    return undefined;
+}
+/**
+ * Wrap a `fetch` response: if non-2xx, throw a `SandboxHttpError` carrying
+ * the status + Retry-After, otherwise return the response for the caller to
+ * parse.
+ */
+async function ensureOk(response, errorPrefix) {
+    if (response.ok)
+        return response;
+    const text = await response.text().catch(() => "");
+    const retryAfterMs = parseRetryAfter(response.headers.get("Retry-After"));
+    throw new SandboxHttpError(`${errorPrefix}: ${response.status} ${text}`, response.status, retryAfterMs);
+}
+/** Whether this error is worth retrying. */
+function isRetryable(err) {
+    if (err instanceof SandboxHttpError)
+        return RETRYABLE_STATUS.has(err.status);
+    // Network-level failures (fetch rejected): typically TypeError "fetch failed"
+    // or AbortError. Retry non-abort errors.
+    if (err instanceof Error) {
+        if (err.name === "AbortError")
+            return false;
+        return true;
+    }
+    return false;
+}
+/**
+ * Retry `fn` up to `maxRetries` times on retryable errors with jittered
+ * exponential backoff. Honors `Retry-After` when the server provides one.
+ * Respects `signal` for prompt cancellation during the backoff wait.
+ */
+async function withRetry(fn, opts) {
+    const maxRetries = opts?.maxRetries ?? exports.DEFAULT_MAX_RETRIES;
+    const base = opts?.retryBaseDelayMs ?? exports.DEFAULT_RETRY_BASE_DELAY_MS;
+    const signal = opts?.signal;
+    for (let attempt = 0;; attempt++) {
+        try {
+            return await fn(attempt);
+        }
+        catch (err) {
+            if (attempt >= maxRetries || !isRetryable(err) || signal?.aborted) {
+                throw err;
+            }
+            const backoff = err instanceof SandboxHttpError && err.retryAfterMs !== undefined
+                ? err.retryAfterMs
+                : base * 2 ** attempt + Math.random() * base;
+            await sleepWithSignal(backoff, signal);
+        }
+    }
+}
+function sleepWithSignal(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(new DOMException("Aborted", "AbortError"));
+            return;
+        }
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(new DOMException("Aborted", "AbortError"));
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+/**
+ * Default part size: 5 MiB. Bottom of Blaxel's recommended 5–10 MB range
+ * and well clear of the Sapiom ingress 8 MiB body-size ceiling (with
+ * room left for multipart form-data overhead).
+ */
+exports.DEFAULT_PART_SIZE = 5 * 1024 * 1024;
+/** Default number of parallel part uploads. */
+exports.DEFAULT_CONCURRENCY = 4;
+/** Default file permissions (Blaxel default). */
+exports.DEFAULT_PERMISSIONS = "0644";
+/**
+ * Normalize any supported content type into a `Blob`.
+ * `Blob.slice()` gives us random-access + lazy reads, so large inputs don't
+ * have to sit materialized in memory.
+ */
+function toBlob(content) {
+    if (content instanceof Blob)
+        return content;
+    if (typeof content === "string") {
+        return new Blob([new TextEncoder().encode(content)]);
+    }
+    return new Blob([content]);
+}
+/**
+ * Split a byte range into part plans.
+ * Always emits at least one part (even for zero-byte inputs) so the caller
+ * still goes through the initiate/upload/complete handshake.
+ */
+function planParts(totalBytes, partSize) {
+    if (!Number.isFinite(partSize) || partSize <= 0) {
+        throw new Error(`partSize must be a positive integer (got ${partSize})`);
+    }
+    const count = totalBytes === 0 ? 1 : Math.ceil(totalBytes / partSize);
+    if (count > exports.MAX_PARTS) {
+        const minPartSize = Math.ceil(totalBytes / exports.MAX_PARTS);
+        throw new Error(`File of ${totalBytes} bytes would require ${count} parts at partSize=${partSize}, ` +
+            `but the server accepts at most ${exports.MAX_PARTS}. Increase partSize to at least ${minPartSize}.`);
+    }
+    const plans = [];
+    for (let i = 0; i < count; i++) {
+        const start = i * partSize;
+        const end = Math.min(start + partSize, totalBytes);
+        plans.push({ partNumber: i + 1, start, end });
+    }
+    return plans;
+}
+/**
+ * Run `worker` over `items` with at most `concurrency` promises in flight.
+ * Rejects on the first worker failure (and stops scheduling further items).
+ */
+async function runWithConcurrency(items, concurrency, worker) {
+    if (!Number.isFinite(concurrency) || concurrency < 1) {
+        throw new Error(`concurrency must be >= 1 (got ${concurrency})`);
+    }
+    const results = new Array(items.length);
+    let next = 0;
+    let failed = false;
+    let firstError;
+    const limit = Math.min(concurrency, items.length);
+    const runners = [];
+    for (let slot = 0; slot < limit; slot++) {
+        runners.push((async () => {
+            while (!failed) {
+                const i = next++;
+                if (i >= items.length)
+                    return;
+                try {
+                    results[i] = await worker(items[i], i);
+                }
+                catch (err) {
+                    if (!failed) {
+                        failed = true;
+                        firstError = err;
+                    }
+                    return;
+                }
+            }
+        })());
+    }
+    await Promise.all(runners);
+    if (failed)
+        throw firstError;
+    return results;
+}
+//# sourceMappingURL=multipart.js.map

package/dist/cjs/multipart.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"multipart.js","sourceRoot":"","sources":["../../src/multipart.ts"],"names":[],"mappings":"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"}

package/dist/cjs/sandbox.d.ts

@@ -1,4 +1,4 @@
-import type { SandboxCreateOptions, ExecOptions, ExecResult, ExecStreamOptions, StreamingExecResult, ProcessStatusResponse } from "./types.js";
+import type { SandboxCreateOptions, ExecOptions, ExecResult, ExecStreamOptions, StreamingExecResult, ProcessStatusResponse, MultipartInitiateResponse, MultipartPartInfo, MultipartUploadedPart, UploadFileOptions } from "./types.js";
 export declare class SapiomSandbox {
     /** Name / identifier of the sandbox. */
     readonly name: string;
@@ -31,6 +31,72 @@ export declare class SapiomSandbox {
      * @returns The file content as a string.
      */
     readFile(path: string): Promise<string>;
+    /**
+     * Upload a file to the sandbox using multipart upload.
+     *
+     * Handles the full initiate → part upload → complete lifecycle, with
+     * parallel part uploads and automatic abort on any failure (including
+     * `signal` aborts).
+     *
+     * Prefer this over {@link writeFile} for binary content or any file over
+     * a few MB. `writeFile` stays available for small text files.
+     *
+     * @param path - File path relative to workspaceRoot.
+     * @param content - Blob, Uint8Array, or string. Strings are UTF-8 encoded.
+     * @param opts - Upload options.
+     */
+    uploadFile(path: string, content: Blob | Uint8Array | string, opts?: UploadFileOptions): Promise<void>;
+    /**
+     * Initiate a multipart upload for a file path.
+     *
+     * Low-level: prefer {@link uploadFile} for the full lifecycle. Use this
+     * when you need custom retry/progress/resumable behavior.
+     */
+    initiateMultipartUpload(path: string, opts?: {
+        permissions?: string;
+        signal?: AbortSignal;
+    }): Promise<MultipartInitiateResponse>;
+    /**
+     * Upload a single part of a multipart upload.
+     *
+     * Low-level: prefer {@link uploadFile} for the full lifecycle.
+     *
+     * @param uploadId - Upload session ID from {@link initiateMultipartUpload}.
+     * @param partNumber - 1-indexed part number (1 to 10000).
+     * @param part - The part bytes.
+     */
+    uploadPart(uploadId: string, partNumber: number, part: Blob | Uint8Array, opts?: {
+        signal?: AbortSignal;
+    }): Promise<MultipartUploadedPart>;
+    /**
+     * Complete a multipart upload by committing the uploaded parts.
+     *
+     * Low-level: prefer {@link uploadFile} for the full lifecycle.
+     */
+    completeMultipartUpload(uploadId: string, parts: Array<{
+        partNumber: number;
+        etag: string;
+    }>, opts?: {
+        signal?: AbortSignal;
+    }): Promise<{
+        message: string;
+        path: string;
+    }>;
+    /**
+     * Abort a multipart upload and clean up any uploaded parts on the server.
+     */
+    abortMultipartUpload(uploadId: string, opts?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+    /**
+     * List the parts already uploaded for a multipart upload.
+     *
+     * Useful for resumable uploads: after reconnecting, call this to see
+     * which part numbers you still need to upload.
+     */
+    listMultipartParts(uploadId: string, opts?: {
+        signal?: AbortSignal;
+    }): Promise<MultipartPartInfo[]>;
     /**
      * Execute a command in the sandbox.
      *

package/dist/cjs/sandbox.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../../src/sandbox.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,oBAAoB,EAEpB,WAAW,EACX,UAAU,EACV,iBAAiB,EACjB,mBAAmB,EAGnB,qBAAqB,EACtB,MAAM,YAAY,CAAC;AA0DpB,qBAAa,aAAa;IACxB,wCAAwC;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,uDAAuD;IACvD,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAE/B;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAE5B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0B;IACjD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAElC,OAAO;IAcP;;OAEG;WACU,MAAM,CAAC,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,aAAa,CAAC;IAwCvE;;;;;OAKG;IACG,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAkB7D;;;;;OAKG;IACG,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAiB7C;;;;;;;;;OASG;IACG,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;IA0BpE;;;;;;;;;OASG;IACG,UAAU,CACd,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,iBAAiB,GACvB,OAAO,CAAC,mBAAmB,CAAC;IA4H/B;;;;;;;OAOG;IACG,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAe7D;;;;;;;;OAQG;IACG,cAAc,CAClB,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE;QAAE,YAAY,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GACvE,OAAO,CAAC,UAAU,CAAC;IAItB;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;YAkBhB,cAAc;YA8Bd,YAAY;CAqC3B"}
+{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../../src/sandbox.ts"],"names":[],"mappings":"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"}