class_WebIdentityInfo for ifconfig.me

class_WebIdentityInfo.ps1

<#
    .SYNOPSIS
        Represents public web identity information of the current machine.
    .DESCRIPTION
        The WebIdentityInfo class represents the public web identity information of the 
        current computer as seen from the ifconfig.me service.
        
        It includes properties such as IP address, user agent, TCP port, HTTP method, encoding, 
        via, and forwarded headers.

        It also includes methods for testing connectivity via ICMP and TCP, changing the output
        format, refreshing the data, and retrieveing WHOIS information for the public IP 
        address.
    .EXAMPLE
        [WebIdentityInfo]::Get()

        Retrieves the current network identity information and returns an instance of the 
        WebIdentityInfo class.
    .EXAMPLE
        $netInfo = [WebIdentityInfo]::Get()
        $netInfo.TestICMP()

        Tests ICMP connectivity to the public IP address of the current computer.
    .EXAMPLE
        $netInfo = [WebIdentityInfo]::Get()
        $netInfo.TestTCP()

        Tests TCP connectivity to the public IP address and port of the current computer.
    .EXAMPLE
        $netInfo = [WebIdentityInfo]::Get()
        $netInfo.ToCSV("~/Desktop/WebIdentityInfo.csv")

        Outputs the current network identity information to a CSV file. 
    .EXAMPLE
        $netInfo = [WebIdentityInfo]::Get()
        $netInfo.ToJSON()
        Outputs the current network identity information to a JSON string.
    .EXAMPLE
        $netInfo = [WebIdentityInfo]::Get()
        $netInfo.Refresh()

        Refreshes the network identity information.
    .EXAMPLE
        $netInfo = [WebIdentityInfo]::Get()
        $netInfo.GetWhois()

        Retrieves WHOIS information for the public IP address.
    .NOTES
        This is a demonstrative class written for the purpose of exploring the concepts of writing
        a PowerShell class for a simple API.
#>

class WebIdentityInfo {
    # VISIBLE PROPERTIES --------------------------------------------------------------------------
    [System.String]
    $IPAddress
    
    [System.String]
    $UserAgent

    [System.Int32]
    $TcpPort

    [System.String]
    [ValidateSet("GET", "PATCH", "POST", "PUT", "DELETE")]
    $Method

    [System.Array]
    $Encoding

    [System.String]
    $Via

    [System.Array]
    $Forwarded

    # HIDDEN PROPERTIES ---------------------------------------------------------------------------
    hidden [System.DateTime]$Timestamp = [System.DateTime]::UtcNow
    hidden [System.Guid]$InstanceId    = [System.Guid]::NewGuid()

    # CONSTRUCTOR ---------------------------------------------------------------------------------
    WebIdentityInfo([System.Object]$ApiResponse) {
        $this.IPAddress     = $ApiResponse.ip_addr
        $this.UserAgent     = $ApiResponse.user_agent
        $this.TcpPort       = $ApiResponse.port
        $this.Method        = $ApiResponse.method
        $this.Via           = $ApiResponse.via
        if ( $ApiResponse.encoding ) {
            $this.Encoding  = $ApiResponse.encoding.Split(',').Trim()
        } else {
            $this.Encoding  = @()
        }
        if ( $ApiResponse.forwarded ) {
            $this.Forwarded = $ApiResponse.forwarded.Split(',').Trim()
        } else {
            $this.Forwarded = @()
        }
    }

    # INSTANCE METHODS ----------------------------------------------------------------------------
    # Attempt to connect to the IP address using ICMP
    [System.Boolean] TestICMP() {
        try {
            $icmpTestParams = @{
                ComputerName = $this.IPAddress
                Count        = 1
                ErrorAction  = 'Stop'
            }
            Test-Connection @icmpTestParams
            return $true
        } catch {
            return $false
        }
    }

    # Attempt to connect to the IP address on the TCP port
    [System.Boolean] TestTCP() {
        try {
            $tcpTestParams = @{
                ComputerName = $this.IPAddress
                Port         = $this.TcpPort
                Count        = 1
                ErrorAction  = 'SilentlyContinue'
            }
            Test-Connection @tcpTestParams
            return $true
        }
        catch {
            return $false
        }
    }

    # Output to CSV file
    [System.IO.FileInfo] ToCSV([System.String]$Path) {
        if ( -not $Path ) {
            $Path = Join-Path -Path $PWD -ChildPath "WebIdentityInfo.csv"
        }

        try {
            $this | Export-Csv -Path $Path -NoTypeInformation -Force
            return Get-Item -Path $Path
        }
        catch {
            throw "Failed to export WebIdentityInfo to CSV file at path '$Path': 
            $($_.Exception.Message)"
        }
    }

    # Output to JSON string
    [System.String] ToJSON() {
        return $this | ConvertTo-Json -Depth 3
    }

    # Refresh the network identity information
    [void] Refresh() {
        try {
            $refreshQueryParams = @{
                Method      = 'GET'
                Uri         = 'https://ifconfig.me/all.json'
                ErrorAction = 'Stop'
            }
            $newQuery = Invoke-RestMethod @refreshQueryParams

            $this.IPAddress = $newQuery.ip_addr
            $this.UserAgent = $newQuery.user_agent
            $this.TcpPort   = $newQuery.port
            $this.Method    = $newQuery.method
            $this.Via       = $newQuery.via
            if ( $newQuery.encoding ) {
                $this.Encoding  = $newQuery.encoding.Split(',').Trim()
            } else {
                $this.Encoding  = @()
            }
            if ( $newQuery.forwarded ) {
                $this.Forwarded = $newQuery.forwarded.Split(',').Trim()
            } else {
                $this.Forwarded = @()
            }
            $this.Timestamp = [System.DateTime]::UtcNow
        }
        catch {
            throw "Failed to refresh network identity information: $($_.Exception.Message)"
        }
    }

    # Get WHOIS information
    [System.Object] GetWhois () {
        try {
            $queryParams = @{
                Method      = 'GET'
                Uri         = "https://whois.arin.net/rest/ip/$($this.IPAddress)"
                ErrorAction = 'Stop'
            }
            $query = (Invoke-RestMethod @queryParams).net
            return $query
        }
        catch {
            throw "Failed to retrieve WHOIS information for IP address $($this.IPAddress): 
            $($_.Exception.Message)"
        }
        
    }

    # STATIC METHODS ------------------------------------------------------------------------------
    # Get current network identity information
    static [WebIdentityInfo] Get() {
        try {
            $query = Invoke-RestMethod -Method GET -Uri 'https://ifconfig.me/all.json'
            return [WebIdentityInfo]::new($query)
        }
        catch {
            throw "Failed to retrieve network identity information: $($_.Exception.Message)"
        }
    }
}