@spec authenticate(NebulaGraphEx.Transport.socket(), binary(), binary(), keyword()) ::
  {:ok, map()} | {:error, term()}

Authenticates against the NebulaGraph server.

Returns {:ok, auth_response} on success, where auth_response is a map:

• :error_code — raw integer error code (0 = success)
• :session_id — integer session ID to use in subsequent calls
• :time_zone_offset_seconds — server timezone offset or nil
• :time_zone_name — server timezone binary or nil
• :error_msg — error message binary or nil

@spec execute(NebulaGraphEx.Transport.socket(), integer(), binary(), keyword()) ::
  {:ok, map()} | {:error, term()}

Executes a nGQL statement and returns an ExecutionResponse map with keys:

• :error_code — integer
• :latency_in_us — server-side latency in microseconds
• :data — nil or a map with :column_names and :rows
• :space_name — binary or nil
• :error_msg — binary or nil
• :comment — binary or nil

@spec execute_json(NebulaGraphEx.Transport.socket(), integer(), binary(), keyword()) ::
  {:ok, binary()} | {:error, term()}

Executes a nGQL statement and returns a raw JSON binary.

Useful for debugging. The caller is responsible for JSON decoding.

@spec execute_with_parameter(
  NebulaGraphEx.Transport.socket(),
  integer(),
  binary(),
  map(),
  keyword()
) :: {:ok, map()} | {:error, term()}

Executes a parameterised nGQL statement.

params is a map with binary keys and Elixir values that are encodable by NebulaGraphEx.Thrift.Types.encode_value/1.

Example

GraphService.execute_with_parameter(
  socket,
  session_id,
  "MATCH (v:Player{name: $name}) RETURN v",
  %{"name" => "Tim Duncan"}
)

@spec signout(NebulaGraphEx.Transport.socket(), integer()) :: :ok | {:error, term()}

Signs out and closes the session. One-way — the server sends no reply.

@spec verify_client_version(
  NebulaGraphEx.Transport.socket(),
  keyword()
) :: {:ok, :ok} | {:error, term()}

Performs the client version handshake. Call immediately after opening the socket, before authenticate/3.

Returns {:ok, :ok} on success or {:error, message}.