@spec connect(E2bEx.Client.t(), String.t(), non_neg_integer()) ::
  {:ok, E2bEx.Sandbox.t()} | {:error, E2bEx.Error.t()}

Connect to (resume) a sandbox with a new timeout (POST /sandboxes/:id/connect).

@spec create(E2bEx.Client.t(), map()) ::
  {:ok, E2bEx.Sandbox.t()} | {:error, E2bEx.Error.t()}

Create a sandbox (POST /sandboxes).

params is a map matching the OpenAPI NewSandbox schema, e.g. %{templateID: "tmpl_1", timeout: 30, metadata: %{user: "abc"}}.

Mount team volumes (see E2bEx.Volumes) with volumeMounts: %{templateID: "tmpl_1", volumeMounts: [%{name: "my-vol", path: "/data"}]}.

@spec get(E2bEx.Client.t(), String.t()) ::
  {:ok, E2bEx.Sandbox.t()} | {:error, E2bEx.Error.t()}

Get a sandbox by id (GET /sandboxes/:id).

@spec kill(E2bEx.Client.t(), String.t()) :: :ok | {:error, E2bEx.Error.t()}

Kill (delete) a sandbox (DELETE /sandboxes/:id).

@spec list(
  E2bEx.Client.t(),
  keyword()
) :: {:ok, [E2bEx.Sandbox.t()]} | {:error, E2bEx.Error.t()}

List running sandboxes (GET /v2/sandboxes).

Options (query)

• :metadata — metadata filter string, e.g. "user=abc&app=prod".
• :state — list of states, e.g. ["running", "paused"].
• :next_token — pagination cursor.
• :limit — page size.

@spec list_metrics(E2bEx.Client.t(), [String.t()]) ::
  {:ok, %{required(String.t()) => E2bEx.SandboxMetric.t()}}
  | {:error, E2bEx.Error.t()}

Get latest metrics for several sandboxes (GET /sandboxes/metrics).

Returns {:ok, %{sandbox_id => E2bEx.SandboxMetric.t()}}.

@spec list_snapshots(
  E2bEx.Client.t(),
  keyword()
) :: {:ok, [E2bEx.Snapshot.t()]} | {:error, E2bEx.Error.t()}

List the team's snapshots (GET /snapshots).

Options (query): :sandbox_id (filter by source sandbox), :next_token, :limit.

@spec logs(E2bEx.Client.t(), String.t(), keyword()) ::
  {:ok, [E2bEx.SandboxLog.t()]} | {:error, E2bEx.Error.t()}

Get structured logs for a sandbox (GET /v2/sandboxes/:id/logs).

Options (query): :cursor, :limit, :direction, :level, :search.

@spec metrics(E2bEx.Client.t(), String.t(), keyword()) ::
  {:ok, [E2bEx.SandboxMetric.t()]} | {:error, E2bEx.Error.t()}

Get metrics for a sandbox (GET /sandboxes/:id/metrics).

Options (query): :start, :end (Unix timestamps, in seconds).

@spec pause(E2bEx.Client.t(), String.t()) :: :ok | {:error, E2bEx.Error.t()}

Pause a sandbox (POST /sandboxes/:id/pause).

@spec refresh(E2bEx.Client.t(), String.t(), keyword()) ::
  :ok | {:error, E2bEx.Error.t()}

Refresh (extend) a sandbox (POST /sandboxes/:id/refreshes).

Options: :duration — extension in seconds (optional).

@spec set_network(E2bEx.Client.t(), String.t(), map()) ::
  :ok | {:error, E2bEx.Error.t()}

Replace a running sandbox's egress network config (PUT /sandboxes/:id/network).

config is a map matching the OpenAPI SandboxNetworkUpdateConfig schema.

@spec set_timeout(E2bEx.Client.t(), String.t(), non_neg_integer()) ::
  :ok | {:error, E2bEx.Error.t()}

Set a sandbox's timeout in seconds from now (POST /sandboxes/:id/timeout).

@spec snapshot(E2bEx.Client.t(), String.t(), keyword()) ::
  {:ok, E2bEx.Snapshot.t()} | {:error, E2bEx.Error.t()}

Snapshot a sandbox into a reusable template (POST /sandboxes/:id/snapshots).

Options: :name — optional snapshot name.