@runblackcat/sdk 0.1.0-alpha.100

package/sdk/dist/index.js

@@ -0,0 +1,751 @@
+// sdk/src/index.ts
+var CAPABILITY_OPS = {
+  EXEC: 1,
+  READ: 2,
+  WRITE: 4,
+  SNAPSHOT: 8,
+  DESTROY: 16,
+  INSPECT: 32,
+  SANDBOX_CREATE: 64,
+  TEMPLATE_RW: 128,
+  PUBLISH: 256,
+  PROCESS_START: 512,
+  PROCESS_INSPECT: 1024,
+  PROCESS_CANCEL: 2048,
+  RENEW: 4096
+};
+var BLACKCAT_ERROR_CODES = {
+  SANDBOX_TRANSITIONING: "sandbox_transitioning",
+  FLEET_UPGRADE_QUIESCING: "fleet_upgrade_quiescing"
+};
+function withTemplate(input) {
+  return { ...input, template: input.template ?? "default" };
+}
+function waitQuery({ wait_secs }) {
+  return wait_secs === undefined ? "" : `?wait_secs=${wait_secs}`;
+}
+
+class BlackcatApiError extends Error {
+  status;
+  code;
+  retryAfter;
+  requestId;
+  details;
+  constructor(status, message, details, retryAfter, requestId) {
+    super(message);
+    this.name = "BlackcatApiError";
+    this.status = status;
+    this.details = details;
+    if (typeof details === "object" && details !== null && !Array.isArray(details)) {
+      const code = details.code;
+      if (typeof code === "string")
+        this.code = code;
+    }
+    this.retryAfter = retryAfter;
+    this.requestId = typeof requestId === "string" && requestId.length === 32 && /^[a-f0-9]{32}$/i.test(requestId) ? requestId : undefined;
+  }
+}
+
+class BlackcatProtocolError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "BlackcatProtocolError";
+  }
+}
+var MAX_FILE_CHUNK = 512 * 1024;
+var MAX_FILE_READ_CHUNK = 1e6;
+var MAX_PROCESS_STDIN = 512 * 1024;
+var MAX_EXEC_STDIN = 512 * 1024;
+function execDeadline(input) {
+  const transportMs = input.timeout_ms + 40000;
+  if (!Number.isSafeInteger(input.timeout_ms) || input.timeout_ms <= 0 || !Number.isSafeInteger(transportMs)) {
+    throw new RangeError("EXEC timeout_ms must be a positive safe integer with room for the transport allowance");
+  }
+  return AbortSignal.timeout(transportMs);
+}
+function pathSegment(value) {
+  return encodeURIComponent(value);
+}
+function bytes(value, field) {
+  if (!Array.isArray(value) || value.some((entry) => typeof entry !== "number")) {
+    throw new BlackcatProtocolError(`gateway response field ${field} is not a byte array`);
+  }
+  return Uint8Array.from(value);
+}
+function requestBody(data) {
+  const copy = new ArrayBuffer(data.byteLength);
+  new Uint8Array(copy).set(data);
+  return copy;
+}
+function epochMillis(value, field) {
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0) {
+    throw new BlackcatProtocolError(`${field} is not an epoch-millisecond timestamp`);
+  }
+  return value;
+}
+function isSystemTime(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value))
+    return false;
+  const row = value;
+  return Number.isSafeInteger(row.secs_since_epoch) && Number(row.secs_since_epoch) >= 0 && Number.isSafeInteger(row.nanos_since_epoch) && Number(row.nanos_since_epoch) >= 0 && Number(row.nanos_since_epoch) < 1e9;
+}
+function parseCreateSandboxResponse(value, requestId) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new BlackcatProtocolError("sandbox create receipt is malformed or belongs to another request");
+  }
+  const row = value;
+  if (row.request_id === requestId && row.state === "prevented") {
+    return value;
+  }
+  if (row.request_id !== requestId || typeof row.id !== "string" || row.id.length === 0 || !["boot", "warm_pool", "restore"].includes(String(row.tier)) || !["placed", "pending", "failed", "destroyed"].includes(String(row.state)) || row.state === "placed" && typeof row.node !== "string" || row.state === "pending" && row.node !== null && typeof row.node !== "string" || row.state === "failed" && (row.node !== null || typeof row.error !== "string") || row.state === "destroyed" && (row.node !== null && typeof row.node !== "string" || typeof row.error !== "string") || !isSystemTime(row.expires_at) || !isSystemTime(row.renewable_until)) {
+    throw new BlackcatProtocolError("sandbox create receipt is malformed or belongs to another request");
+  }
+  return value;
+}
+var BATCH_STATES = ["pending", "placed", "failed", "destroyed"];
+function parseSandboxBatch(value, requestId) {
+  const malformed = () => new BlackcatProtocolError("sandbox batch is malformed or belongs to another request");
+  if (typeof value !== "object" || value === null || Array.isArray(value))
+    throw malformed();
+  const row = value;
+  if (row.request_id === requestId && row.state === "prevented") {
+    return value;
+  }
+  if (row.request_id !== requestId || typeof row.count !== "number" || typeof row.counts !== "object" || row.counts === null || !Array.isArray(row.members) || row.members.length !== row.count || !row.members.every((member) => {
+    const m = member;
+    return typeof m === "object" && m !== null && typeof m.request_id === "string" && typeof m.id === "string" && BATCH_STATES.includes(String(m.state));
+  })) {
+    throw malformed();
+  }
+  return value;
+}
+function parseMintTokenResponse(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new BlackcatProtocolError("token mint response is not an object");
+  }
+  const row = value;
+  if (typeof row.token !== "string" || typeof row.token_id !== "string") {
+    throw new BlackcatProtocolError("token mint response is missing the token");
+  }
+  return {
+    token: row.token,
+    token_id: row.token_id,
+    expires_at: epochMillis(row.expires_at, "token expires_at"),
+    renewable_until: epochMillis(row.renewable_until, "token renewable_until")
+  };
+}
+function assertSecureBlackcatGatewayUrl(baseUrl) {
+  let parsed;
+  try {
+    parsed = new URL(baseUrl);
+  } catch {
+    throw new Error(`Blackcat gateway URL is invalid: ${baseUrl}`);
+  }
+  if (parsed.protocol !== "https:") {
+    throw new Error("Blackcat gateway URL must use https when API-key authenticated");
+  }
+}
+function execResult(value) {
+  if (typeof value !== "object" || value === null) {
+    throw new BlackcatProtocolError("gateway exec response is not an object");
+  }
+  const row = value;
+  const exitCode = row.exit_code;
+  if (exitCode !== null && typeof exitCode !== "number") {
+    throw new BlackcatProtocolError("gateway exec response has an invalid exit_code");
+  }
+  if (typeof row.timed_out !== "boolean" || row.timed_out && exitCode !== null) {
+    throw new BlackcatProtocolError("gateway exec response has an invalid timed_out field");
+  }
+  return {
+    exit_code: exitCode,
+    timed_out: row.timed_out,
+    stdout: bytes(row.stdout, "stdout"),
+    stderr: bytes(row.stderr, "stderr")
+  };
+}
+function execStreamChunk(value) {
+  if (typeof value !== "object" || value === null) {
+    throw new BlackcatProtocolError("gateway exec stream item is not an object");
+  }
+  const row = value;
+  if (typeof row.done !== "boolean") {
+    throw new BlackcatProtocolError("gateway exec stream item has an invalid done field");
+  }
+  const exitCode = row.exit_code;
+  if (exitCode !== null && typeof exitCode !== "number") {
+    throw new BlackcatProtocolError("gateway exec stream item has an invalid exit_code");
+  }
+  if (typeof row.timed_out !== "boolean" || row.timed_out && (!row.done || exitCode !== null)) {
+    throw new BlackcatProtocolError("gateway exec stream item has an invalid timed_out field");
+  }
+  if (!row.done && exitCode !== null) {
+    throw new BlackcatProtocolError("gateway exec stream item has an exit_code before completion");
+  }
+  return {
+    stdout: bytes(row.stdout, "stdout"),
+    stderr: bytes(row.stderr, "stderr"),
+    done: row.done,
+    exit_code: exitCode,
+    timed_out: row.timed_out
+  };
+}
+async function apiError(response) {
+  const text = await response.text();
+  let details = text;
+  let message = text || response.statusText || `Blackcat request failed (${response.status})`;
+  if (text) {
+    try {
+      const parsed = JSON.parse(text);
+      details = parsed;
+      if (typeof parsed === "object" && parsed !== null) {
+        const error = parsed.error;
+        if (typeof error === "string")
+          message = error;
+      }
+    } catch {}
+  }
+  const retryHeader = response.headers.get("retry-after");
+  const retryAfter = retryHeader === null ? undefined : Number(retryHeader);
+  return new BlackcatApiError(response.status, message, details, retryAfter !== undefined && Number.isFinite(retryAfter) ? retryAfter : undefined, response.headers.get("x-blackcat-request-id") ?? undefined);
+}
+
+class GatewayClient {
+  baseUrl;
+  apiKey;
+  token;
+  tokenId;
+  tokenExpiresAt;
+  renewCapability;
+  caPem;
+  fetcher;
+  renewalInFlight;
+  constructor(options) {
+    this.baseUrl = options.baseUrl.endsWith("/") ? options.baseUrl : `${options.baseUrl}/`;
+    this.apiKey = options.apiKey;
+    this.token = options.token;
+    this.tokenId = options.tokenId ?? options.token_id;
+    this.tokenExpiresAt = options.tokenExpiresAt ?? options.token_expires_at;
+    this.renewCapability = options.renewCapability;
+    this.caPem = options.caPem;
+    this.fetcher = options.fetch ?? globalThis.fetch;
+  }
+  credential(kind) {
+    const credential = kind === "apiKey" ? this.apiKey : kind === "token" ? this.token : this.token ?? this.apiKey;
+    if (!credential) {
+      throw new Error(kind === "apiKey" ? "Blackcat API key is required for this operation" : "Blackcat bearer credential is required for this operation");
+    }
+    return credential;
+  }
+  async json(method, path, body, kind = "either", timeout, signal, extraHeaders) {
+    if (kind !== "apiKey" && !path.endsWith("/renew"))
+      await this.renewIfNeeded(signal);
+    const headers = new Headers({ Authorization: `Bearer ${this.credential(kind)}` });
+    for (const [name, value] of new Headers(extraHeaders))
+      headers.set(name, value);
+    if (body !== undefined)
+      headers.set("content-type", "application/json");
+    const response = await this.fetcher(new URL(path, this.baseUrl), {
+      method,
+      headers,
+      body: body === undefined ? undefined : JSON.stringify(body),
+      ...timeout === false ? { timeout } : {},
+      ...this.caPem === undefined ? {} : { tls: { ca: this.caPem } },
+      signal
+    });
+    if (!response.ok)
+      throw await apiError(response);
+    if (response.status === 204)
+      return;
+    return await response.json();
+  }
+  async raw(method, path, body, kind = "either", contentType, timeout, signal) {
+    if (kind !== "apiKey" && !path.endsWith("/renew"))
+      await this.renewIfNeeded(signal);
+    const headers = new Headers({ Authorization: `Bearer ${this.credential(kind)}` });
+    if (contentType)
+      headers.set("content-type", contentType);
+    const response = await this.fetcher(new URL(path, this.baseUrl), {
+      method,
+      headers,
+      body,
+      signal,
+      ...timeout === false ? { timeout } : {},
+      ...this.caPem === undefined ? {} : { tls: { ca: this.caPem } }
+    });
+    if (!response.ok)
+      throw await apiError(response);
+    return response;
+  }
+  async renewIfNeeded(signal) {
+    if (!this.tokenId || !this.tokenExpiresAt || this.tokenExpiresAt - Date.now() > 30000)
+      return;
+    if (!this.renewalInFlight) {
+      const tokenId = this.tokenId;
+      this.renewalInFlight = (async () => {
+        if (this.renewCapability) {
+          const minted = parseMintTokenResponse(await this.renewCapability());
+          this.token = minted.token;
+          this.tokenId = minted.token_id;
+          this.tokenExpiresAt = minted.expires_at;
+          return;
+        }
+        const result = await this.json("POST", `/v1/tokens/${pathSegment(tokenId)}/renew`, undefined, "token", undefined, signal);
+        this.tokenExpiresAt = epochMillis(result.expires_at, "token renewal expires_at");
+      })().finally(() => {
+        this.renewalInFlight = undefined;
+      });
+    }
+    await this.renewalInFlight;
+  }
+  async* stream(method, path, body, kind = "either", contentType, renew = false, signal) {
+    if (renew)
+      await this.renewIfNeeded(signal);
+    const response = await this.raw(method, path, body, kind, contentType, false, signal);
+    if (!response.body)
+      throw new BlackcatProtocolError("gateway response has no stream body");
+    const reader = response.body.getReader();
+    let timer;
+    let closed = false;
+    let rejectRenewal;
+    const renewalFailure = new Promise((_, reject) => {
+      rejectRenewal = reject;
+    });
+    const scheduleRenewal = () => {
+      if (!renew || !this.tokenId || !this.tokenExpiresAt)
+        return;
+      const delay = Math.max(250, this.tokenExpiresAt - Date.now() - 30000);
+      timer = setTimeout(async () => {
+        if (closed)
+          return;
+        try {
+          await this.renewIfNeeded(signal);
+          if (!closed)
+            scheduleRenewal();
+        } catch (error) {
+          rejectRenewal(error);
+        }
+      }, delay);
+    };
+    scheduleRenewal();
+    try {
+      while (true) {
+        const part = await Promise.race([reader.read(), renewalFailure]);
+        if (part.done)
+          return;
+        yield part.value;
+      }
+    } finally {
+      closed = true;
+      if (timer !== undefined)
+        clearTimeout(timer);
+      try {
+        await reader.cancel();
+      } finally {
+        reader.releaseLock();
+      }
+    }
+  }
+}
+
+class TemplatesResource {
+  client;
+  constructor(client) {
+    this.client = client;
+  }
+  create(input) {
+    return this.client.json("POST", "/v1/templates", input, "either");
+  }
+  list() {
+    return this.client.json("GET", "/v1/templates", undefined, "either");
+  }
+  async uploadImage(archive, options) {
+    const response = await this.client.raw("POST", "/v1/template-images", archive, "either", "application/octet-stream", false, options?.signal);
+    return await response.json();
+  }
+  activate(id) {
+    return this.client.json("POST", `/v1/templates/${pathSegment(id)}/activate`, undefined, "either");
+  }
+}
+
+class TemplateResourcesResource {
+  client;
+  constructor(client) {
+    this.client = client;
+  }
+  get(name) {
+    return this.client.json("GET", `/v1/template-resources/${pathSegment(name)}`, undefined, "either");
+  }
+  configure(name, input) {
+    return this.client.json("PUT", `/v1/template-resources/${pathSegment(name)}`, input, "either");
+  }
+  delete(name) {
+    return this.client.json("DELETE", `/v1/template-resources/${pathSegment(name)}`, undefined, "either");
+  }
+}
+
+class TemplateBuildsResource {
+  client;
+  constructor(client) {
+    this.client = client;
+  }
+  create(input) {
+    return this.client.json("POST", "/v1/template-builds", input, "either");
+  }
+  get(id) {
+    return this.client.json("GET", `/v1/template-builds/${pathSegment(id)}`, undefined, "either");
+  }
+  retry(id) {
+    return this.client.json("POST", `/v1/template-builds/${pathSegment(id)}/retry`, undefined, "either");
+  }
+}
+
+class TokensResource {
+  client;
+  constructor(client) {
+    this.client = client;
+  }
+  async mint(input) {
+    return parseMintTokenResponse(await this.client.json("POST", "/v1/tokens", input, "apiKey"));
+  }
+  renew(id) {
+    return this.client.json("POST", `/v1/tokens/${pathSegment(id)}/renew`, undefined, "token").then((response) => {
+      const parsed = { expires_at: epochMillis(response.expires_at, "token renewal expires_at") };
+      if (this.client.tokenId === id)
+        this.client.tokenExpiresAt = parsed.expires_at;
+      return parsed;
+    });
+  }
+  revoke(id) {
+    return this.client.json("DELETE", `/v1/tokens/${pathSegment(id)}`, undefined, "either");
+  }
+}
+
+class FleetResource {
+  client;
+  constructor(client) {
+    this.client = client;
+  }
+  list() {
+    return this.client.json("GET", "/v1/fleet", undefined, "either");
+  }
+}
+
+class ReservationsResource {
+  client;
+  constructor(client) {
+    this.client = client;
+  }
+  create(input) {
+    return this.client.json("POST", "/v1/capacity-reservations", input, "either");
+  }
+  get(id) {
+    return this.client.json("GET", `/v1/capacity-reservations/${pathSegment(id)}`, undefined, "either");
+  }
+  release(id) {
+    return this.client.json("DELETE", `/v1/capacity-reservations/${pathSegment(id)}`, undefined, "either");
+  }
+  renew(id, input) {
+    return this.client.json("POST", `/v1/capacity-reservations/${pathSegment(id)}/renew`, input, "either");
+  }
+}
+
+class SandboxesResource {
+  client;
+  constructor(client) {
+    this.client = client;
+  }
+  list() {
+    return this.client.json("GET", "/v1/sandboxes", undefined, "either");
+  }
+  async create(input, options = {}) {
+    return parseCreateSandboxResponse(await this.client.json("POST", `/v1/sandboxes${waitQuery(options)}`, withTemplate(input), "either", false), input.request_id);
+  }
+  async createBatch(input) {
+    return parseSandboxBatch(await this.client.json("POST", "/v1/sandboxes", withTemplate(input), "either", false), input.request_id);
+  }
+  async batch(requestId) {
+    return parseSandboxBatch(await this.client.json("GET", `/v1/sandboxes/batches/${pathSegment(requestId)}`, undefined, "either"), requestId);
+  }
+  async acquisition(requestId, options = {}) {
+    return parseCreateSandboxResponse(await this.client.json("GET", `/v1/sandboxes/acquisitions/${pathSegment(requestId)}${waitQuery(options)}`, undefined, "either", options.wait_secs === undefined ? undefined : false), requestId);
+  }
+  async cancelAcquisition(requestId) {
+    return parseCreateSandboxResponse(await this.client.json("DELETE", `/v1/sandboxes/acquisitions/${pathSegment(requestId)}`, undefined, "either"), requestId);
+  }
+  get(id) {
+    return this.client.json("GET", `/v1/sandboxes/${pathSegment(id)}`, undefined, "either");
+  }
+  renew(id, ttl_secs) {
+    return this.client.json("POST", `/v1/sandboxes/${pathSegment(id)}/renew`, { ttl_secs }, "either");
+  }
+  grantSshKey(id, input) {
+    return this.client.json("POST", `/v1/sandboxes/${pathSegment(id)}/ssh-keys`, input, "either");
+  }
+  async portConnection(id, port, path = "/") {
+    if (!Number.isInteger(port) || port < 1 || port > 65535)
+      throw new RangeError("port must be 1-65535");
+    if (!path.startsWith("/"))
+      throw new RangeError("path must start with /");
+    await this.client.renewIfNeeded();
+    const base = new URL(`v1/sandboxes/${pathSegment(id)}/ports/${port}/connect`, this.client.baseUrl);
+    const url = `${base.href}${path.startsWith("/?") || path === "/" ? path.slice(1) : path}`;
+    return {
+      url,
+      websocketUrl: url.replace(/^http/, "ws"),
+      headers: { Authorization: `Bearer ${this.client.credential("either")}` }
+    };
+  }
+  async exec(id, input) {
+    return this.client.json("POST", `/v1/sandboxes/${pathSegment(id)}/exec`, input, "either", false, execDeadline(input)).then(execResult);
+  }
+  async* execStream(id, input) {
+    if (input.stdin !== undefined && input.stdin.length > MAX_EXEC_STDIN) {
+      throw new RangeError(`EXEC stdin exceeds the ${MAX_EXEC_STDIN / 1024} KiB limit`);
+    }
+    let lineBuffer = "";
+    let done = false;
+    const accept = (value) => {
+      if (done)
+        throw new BlackcatProtocolError("gateway sent data after exec completed");
+      const chunk = execStreamChunk(value);
+      done = chunk.done;
+      return chunk;
+    };
+    const decoder = new TextDecoder;
+    for await (const chunk of this.client.stream("POST", `/v1/sandboxes/${pathSegment(id)}/exec/stream`, JSON.stringify(input), "either", "application/json", true, execDeadline(input))) {
+      lineBuffer += decoder.decode(chunk, { stream: true });
+      const lines = lineBuffer.split(`
+`);
+      lineBuffer = lines.pop() ?? "";
+      for (const line of lines) {
+        if (line.trim())
+          yield accept(JSON.parse(line));
+      }
+    }
+    lineBuffer += decoder.decode();
+    if (lineBuffer.trim())
+      yield accept(JSON.parse(lineBuffer));
+    if (!done)
+      throw new BlackcatProtocolError("gateway exec stream ended before its terminal result");
+  }
+  startProcess(id, requestId, input) {
+    if (input.stdin && input.stdin.length > MAX_PROCESS_STDIN) {
+      throw new RangeError(`process stdin exceeds ${MAX_PROCESS_STDIN} bytes`);
+    }
+    return this.client.json("POST", `/v1/sandboxes/${pathSegment(id)}/processes`, {
+      ...input,
+      ...input.stdin === undefined ? {} : { stdin: Array.from(input.stdin) }
+    }, "either", false, undefined, { "idempotency-key": requestId });
+  }
+  getProcess(id, processId) {
+    return this.client.json("GET", `/v1/sandboxes/${pathSegment(id)}/processes/${pathSegment(processId)}`, undefined, "either");
+  }
+  async processLogs(id, processId, input = {}) {
+    const options = typeof input === "number" ? { stdout_offset: 0, stderr_offset: 0, max_bytes: input } : input;
+    const query = new URLSearchParams;
+    if (options.stdout_offset !== undefined)
+      query.set("stdout_offset", String(options.stdout_offset));
+    if (options.stderr_offset !== undefined)
+      query.set("stderr_offset", String(options.stderr_offset));
+    if (options.max_bytes !== undefined)
+      query.set("max_bytes", String(options.max_bytes));
+    const suffix = query.size === 0 ? "" : `?${query.toString()}`;
+    const response = await this.client.json("GET", `/v1/sandboxes/${pathSegment(id)}/processes/${pathSegment(processId)}/logs${suffix}`, undefined, "either");
+    return {
+      ...response,
+      logs: {
+        ...response.logs,
+        stdout: bytes(response.logs.stdout, "logs.stdout"),
+        stderr: bytes(response.logs.stderr, "logs.stderr")
+      }
+    };
+  }
+  cancelProcess(id, processId) {
+    return this.client.json("DELETE", `/v1/sandboxes/${pathSegment(id)}/processes/${pathSegment(processId)}`, undefined, "either");
+  }
+  prepare(id, input, idempotencyKey) {
+    return this.client.json("POST", `/v1/sandboxes/${pathSegment(id)}/prepare`, input, "either", undefined, undefined, { "idempotency-key": idempotencyKey });
+  }
+  logs(id) {
+    return this.client.stream("GET", `/v1/sandboxes/${pathSegment(id)}/logs`, undefined, "either", undefined, true);
+  }
+  async readFileChunk(id, input) {
+    if (input.offset < 0 || input.length <= 0 || input.length > MAX_FILE_READ_CHUNK) {
+      throw new RangeError(`file read offset must be non-negative and length must be between 1 and ${MAX_FILE_READ_CHUNK}`);
+    }
+    const query = new URLSearchParams({
+      path: input.path,
+      offset: String(input.offset),
+      length: String(input.length)
+    });
+    const response = await this.client.raw("GET", `/v1/sandboxes/${pathSegment(id)}/files/read?${query.toString()}`, undefined, "either");
+    const data = new Uint8Array(await response.arrayBuffer());
+    const offset = Number(response.headers.get("x-blackcat-offset") ?? input.offset);
+    const eof = response.headers.get("x-blackcat-eof") === "true";
+    return { data, offset, eof };
+  }
+  async* readFileStream(id, input) {
+    const start = input.offset ?? 0;
+    const chunkSize = input.chunk_size ?? MAX_FILE_READ_CHUNK;
+    if (start < 0 || input.length !== undefined && input.length < 0) {
+      throw new RangeError("file read offset and length must be non-negative");
+    }
+    if (chunkSize <= 0 || chunkSize > MAX_FILE_READ_CHUNK) {
+      throw new RangeError(`file read chunk_size must be between 1 and ${MAX_FILE_READ_CHUNK}`);
+    }
+    let offset = start;
+    let remaining = input.length;
+    while (remaining === undefined || remaining > 0) {
+      const length = Math.min(chunkSize, remaining ?? chunkSize);
+      const chunk = await this.readFileChunk(id, { path: input.path, offset, length });
+      yield chunk;
+      offset += chunk.data.length;
+      if (chunk.eof || chunk.data.length === 0)
+        return;
+      if (remaining !== undefined)
+        remaining -= chunk.data.length;
+    }
+  }
+  async readFile(id, input) {
+    const chunks = [];
+    for await (const chunk of this.readFileStream(id, input)) {
+      chunks.push(chunk.data);
+    }
+    const total = chunks.reduce((sum, chunk) => sum + chunk.length, 0);
+    const output = new Uint8Array(total);
+    let cursor = 0;
+    for (const chunk of chunks) {
+      output.set(chunk, cursor);
+      cursor += chunk.length;
+    }
+    return output;
+  }
+  async writeFileChunk(id, input) {
+    if (input.data.length > MAX_FILE_CHUNK) {
+      throw new RangeError(`file write chunk exceeds ${MAX_FILE_CHUNK} bytes`);
+    }
+    const query = new URLSearchParams({
+      path: input.path,
+      offset: String(input.offset),
+      truncate: String(input.truncate)
+    });
+    await this.client.raw("POST", `/v1/sandboxes/${pathSegment(id)}/files/write?${query.toString()}`, requestBody(input.data), "either", "application/octet-stream");
+  }
+  async writeFileStream(id, input) {
+    const start = input.offset ?? 0;
+    if (start < 0)
+      throw new RangeError("file write offset must be non-negative");
+    let offset = start;
+    let written = 0;
+    let first = true;
+    for await (const chunk of input.data) {
+      for (let cursor = 0;cursor < chunk.length; cursor += MAX_FILE_CHUNK) {
+        const data = chunk.slice(cursor, cursor + MAX_FILE_CHUNK);
+        await this.writeFileChunk(id, {
+          path: input.path,
+          offset,
+          data,
+          truncate: (input.truncate ?? true) && first
+        });
+        first = false;
+        offset += data.length;
+        written += data.length;
+      }
+    }
+    if (first && (input.truncate ?? true)) {
+      await this.writeFileChunk(id, {
+        path: input.path,
+        offset,
+        data: new Uint8Array(0),
+        truncate: true
+      });
+    }
+    return written;
+  }
+  async writeFile(id, input) {
+    async function* oneChunk() {
+      yield input.data;
+    }
+    return this.writeFileStream(id, {
+      path: input.path,
+      data: oneChunk(),
+      offset: input.offset,
+      truncate: input.truncate
+    });
+  }
+  snapshot(id) {
+    return this.client.json("POST", `/v1/sandboxes/${pathSegment(id)}/snapshot`, undefined, "either");
+  }
+  pause(id) {
+    return this.client.raw("POST", `/v1/sandboxes/${pathSegment(id)}/pause`, undefined, "either").then(() => {
+      return;
+    });
+  }
+  hibernate(id, input) {
+    return this.client.raw("POST", `/v1/sandboxes/${pathSegment(id)}/hibernate`, input === undefined ? undefined : JSON.stringify(input), "either", input === undefined ? undefined : "application/json", false).then(() => {
+      return;
+    });
+  }
+  resize(id, input) {
+    return this.client.json("POST", `/v1/sandboxes/${pathSegment(id)}/resize`, { ...input, request_id: input.request_id ?? `resize-${crypto.randomUUID()}` }, "either", false);
+  }
+  resume(id) {
+    return this.client.raw("POST", `/v1/sandboxes/${pathSegment(id)}/resume`, undefined, "either").then(() => {
+      return;
+    });
+  }
+  destroy(id) {
+    return this.client.json("DELETE", `/v1/sandboxes/${pathSegment(id)}`, undefined, "either");
+  }
+}
+
+class BlackcatClient extends GatewayClient {
+  templates;
+  templateResources;
+  templateBuilds;
+  sandboxes;
+  tokens;
+  fleet;
+  reservations;
+  constructor(options) {
+    if (options.apiKey !== undefined)
+      assertSecureBlackcatGatewayUrl(options.baseUrl);
+    super(options);
+    this.templates = new TemplatesResource(this);
+    this.templateResources = new TemplateResourcesResource(this);
+    this.templateBuilds = new TemplateBuildsResource(this);
+    this.sandboxes = new SandboxesResource(this);
+    this.tokens = new TokensResource(this);
+    this.fleet = new FleetResource(this);
+    this.reservations = new ReservationsResource(this);
+  }
+  withToken(token, renewCapability) {
+    const capability = typeof token === "string" ? undefined : token;
+    return new BlackcatClient({
+      baseUrl: this.baseUrl,
+      apiKey: this.apiKey,
+      token: capability?.token ?? (typeof token === "string" ? token : undefined),
+      tokenId: capability?.token_id,
+      tokenExpiresAt: capability?.expires_at,
+      renewCapability,
+      caPem: this.caPem,
+      fetch: this.fetcher
+    });
+  }
+}
+export {
+  parseSandboxBatch,
+  parseCreateSandboxResponse,
+  epochMillis,
+  assertSecureBlackcatGatewayUrl,
+  MAX_PROCESS_STDIN,
+  MAX_FILE_CHUNK as MAX_FILE_WRITE_CHUNK,
+  MAX_FILE_READ_CHUNK,
+  MAX_FILE_CHUNK,
+  MAX_EXEC_STDIN,
+  CAPABILITY_OPS,
+  BlackcatClient,
+  BlackcatApiError,
+  BLACKCAT_ERROR_CODES
+};