@spec delete(ArchAstro.Client.t(), String.t()) ::
  {:ok, :ok} | {:error, ArchAstro.Error.reason()}

Delete a computer

Permanently deletes the specified computer and releases all associated infrastructure resources. This action is irreversible — once deleted, the computer cannot be recovered and its ID becomes invalid.

Requires an app-scoped API key. The computer must belong to the same app. Returns 204 No Content on success.

Empty response body. Returns HTTP 204 on success.

@spec exec(
  ArchAstro.Client.t(),
  String.t(),
  ArchAstro.Types.Operations.PostApiV1AgentComputersComputerExec.Input.t()
) ::
  {:ok, ArchAstro.Types.ComputerExecResult.t()}
  | {:error, ArchAstro.Error.reason()}

Execute a command on a computer

Runs a shell command on the specified computer and returns its combined output and exit code. The call blocks until the command completes; there is no streaming or timeout override — plan accordingly for long-running commands.

Requires an app-scoped API key. The computer must be in the running state. Commands run as the default unprivileged user on the computer. A non-zero exit_code in the response does not produce an HTTP error; inspect exit_code and output to determine success.

The output and exit code produced by the command.

@spec get(ArchAstro.Client.t(), String.t()) ::
  {:ok, ArchAstro.Types.AgentComputer.t()} | {:error, ArchAstro.Error.reason()}

Retrieve a computer

Returns the computer identified by computer. The computer must belong to the app associated with the API key.

Use this endpoint to inspect a computer's current status, region, config, and metadata after provisioning or to verify its state before issuing commands. For a live status update, use the refresh endpoint instead.

The requested computer.

@spec refresh(ArchAstro.Client.t(), String.t()) ::
  {:ok, ArchAstro.Types.AgentComputer.t()} | {:error, ArchAstro.Error.reason()}

Refresh a computer's status

Fetches the latest status for the specified computer from the upstream provisioning provider and updates the platform record accordingly. Use this endpoint to reconcile a computer whose status appears stale or stuck in a transitional state such as provisioning.

Requires an app-scoped API key. Returns 422 if the computer has not been fully provisioned yet. The updated computer object is returned on success.

The computer record with its status updated from the provisioning provider.