[Feature] User - Followers - Use the REST API to get information about followers of authenticated users (#52)

- Fixes #47
  - Add-GitHubUserFollowing (Follow-GitHubUser)
  - Get-GitHubUserFollowers
  - Get-GitHubUserFollowing
  - Remove-GitHubUserFollowing (Unfollow-GitHubUser)
  - Test-GitHubUserFollows

Author: MariusStorhaug

src/GitHub/private/Users/Followers/Get-GitHubUserFollowersOfUser.ps1

@@ -0,0 +1,46 @@
+filter Get-GitHubUserFollowersOfUser {
+    <#
+        .SYNOPSIS
+        List followers of a user
+
+        .DESCRIPTION
+        Lists the people following the specified user.
+
+        .EXAMPLE
+        Get-GitHubUserFollowersOfUser -Username 'octocat'
+
+        Gets all followers of user 'octocat'.
+
+        .NOTES
+        https://docs.github.com/rest/users/followers#list-followers-of-a-user
+
+    #>
+    [OutputType([pscustomobject])]
+    [CmdletBinding()]
+    param (
+        # The handle for the GitHub user account.
+        [Parameter(
+            Mandatory,
+            ValueFromPipeline,
+            ValueFromPipelineByPropertyName
+        )]
+        [Alias('login')]
+        [string] $Username,
+
+        # The number of results per page (max 100).
+        [Parameter()]
+        [int] $PerPage = 30
+    )
+
+    $body = $PSBoundParameters | ConvertFrom-HashTable | ConvertTo-HashTable -NameCasingStyle snake_case
+    Remove-HashtableEntries -Hashtable $body -RemoveNames 'username'
+
+    $inputObject = @{
+        APIEndpoint = "/users/$Username/followers"
+        Method      = 'GET'
+        Body        = $body
+    }
+
+    (Invoke-GitHubAPI @inputObject).Response
+
+}

src/GitHub/private/Users/Followers/Get-GitHubUserFollowingMe.ps1

@@ -0,0 +1,36 @@
+filter Get-GitHubUserFollowingMe {
+    <#
+        .SYNOPSIS
+        List the people the authenticated user follows
+
+        .DESCRIPTION
+        Lists the people who the authenticated user follows.
+
+        .EXAMPLE
+        Get-GitHubUserFollowingMe
+
+        Gets all people the authenticated user follows.
+
+        .NOTES
+        https://docs.github.com/rest/users/followers#list-the-people-the-authenticated-user-follows
+
+    #>
+    [OutputType([pscustomobject])]
+    [CmdletBinding()]
+    param (
+        # The number of results per page (max 100).
+        [Parameter()]
+        [int] $PerPage = 30
+    )
+
+    $body = $PSBoundParameters | ConvertFrom-HashTable | ConvertTo-HashTable -NameCasingStyle snake_case
+
+    $inputObject = @{
+        APIEndpoint = '/user/following'
+        Method      = 'GET'
+        Body        = $body
+    }
+
+    (Invoke-GitHubAPI @inputObject).Response
+
+}

src/GitHub/private/Users/Followers/Get-GitHubUserFollowingUser.ps1

@@ -0,0 +1,46 @@
+filter Get-GitHubUserFollowingUser {
+    <#
+        .SYNOPSIS
+        List the people a user follows
+
+        .DESCRIPTION
+        Lists the people who the specified user follows.
+
+        .EXAMPLE
+        Get-GitHubUserFollowingUser -Username 'octocat'
+
+        Gets all people that 'octocat' follows.
+
+        .NOTES
+        https://docs.github.com/rest/users/followers#list-the-people-a-user-follows
+
+    #>
+    [OutputType([pscustomobject])]
+    [CmdletBinding()]
+    param (
+        # The handle for the GitHub user account.
+        [Parameter(
+            Mandatory,
+            ValueFromPipeline,
+            ValueFromPipelineByPropertyName
+        )]
+        [Alias('login')]
+        [string] $Username,
+
+        # The number of results per page (max 100).
+        [Parameter()]
+        [int] $PerPage = 30
+    )
+
+    $body = $PSBoundParameters | ConvertFrom-HashTable | ConvertTo-HashTable -NameCasingStyle snake_case
+    Remove-HashtableEntries -Hashtable $body -RemoveNames 'username'
+
+    $inputObject = @{
+        APIEndpoint = "/users/$Username/following"
+        Method      = 'GET'
+        Body        = $body
+    }
+
+    (Invoke-GitHubAPI @inputObject).Response
+
+}

src/GitHub/private/Users/Followers/Get-GitHubUserMyFollowers.ps1

@@ -0,0 +1,36 @@
+filter Get-GitHubUserMyFollowers {
+    <#
+        .SYNOPSIS
+        List followers of the authenticated user
+
+        .DESCRIPTION
+        Lists the people following the authenticated user.
+
+        .EXAMPLE
+        Get-GitHubUserMyFollowers
+
+        Gets all followers of the authenticated user.
+
+        .NOTES
+        https://docs.github.com/rest/users/followers#list-followers-of-the-authenticated-user
+
+    #>
+    [OutputType([pscustomobject])]
+    [CmdletBinding()]
+    param (
+        # The number of results per page (max 100).
+        [Parameter()]
+        [int] $PerPage = 30
+    )
+
+    $body = $PSBoundParameters | ConvertFrom-HashTable | ConvertTo-HashTable -NameCasingStyle snake_case
+
+    $inputObject = @{
+        APIEndpoint = '/user/followers'
+        Method      = 'GET'
+        Body        = $body
+    }
+
+    (Invoke-GitHubAPI @inputObject).Response
+
+}

src/GitHub/private/Users/Followers/Test-GitHubUserFollowedByMe.ps1

@@ -0,0 +1,45 @@
+filter Test-GitHubUserFollowedByMe {
+    <#
+        .SYNOPSIS
+        Check if a person is followed by the authenticated user
+
+        .DESCRIPTION
+        Returns a 204 if the given user is followed by the authenticated user.
+        Returns a 404 if the user is not followed by the authenticated user.
+
+        .EXAMPLE
+        Test-GitHubUserFollowedByMe -Username 'octocat'
+
+        Checks if the authenticated user follows the user 'octocat'.
+
+        .NOTES
+        https://docs.github.com/rest/users/followers#check-if-a-person-is-followed-by-the-authenticated-user
+
+    #>
+    [OutputType([bool])]
+    [CmdletBinding()]
+    param (
+        # The handle for the GitHub user account.
+        [Parameter(
+            Mandatory,
+            ValueFromPipelineByPropertyName
+        )]
+        [string] $Username
+    )
+
+    $inputObject = @{
+        APIEndpoint = "/user/following/$Username"
+        Method      = 'GET'
+    }
+
+    try {
+        $null = (Invoke-GitHubAPI @inputObject)
+        return $true
+    } catch {
+        if ($_.Exception.Response.StatusCode.Value__ -eq 404) {
+            return $false
+        } else {
+            throw $_
+        }
+    }
+}

src/GitHub/private/Users/Followers/Test-GitHubUserFollowedByUser.ps1

@@ -0,0 +1,51 @@
+filter Test-GitHubUserFollowedByUser {
+    <#
+        .SYNOPSIS
+        Check if a user follows another user
+
+        .DESCRIPTION
+        Checks if a user follows another user.
+
+        .EXAMPLE
+        Test-GitHubUserFollowedByUser -Username 'octocat' -Follows 'ratstallion'
+
+        Checks if the user 'octocat' follows the user 'ratstallion'.
+
+        .NOTES
+        https://docs.github.com/rest/users/followers#check-if-a-user-follows-another-user
+
+    #>
+    [OutputType([bool])]
+    [CmdletBinding()]
+    param (
+        # The handle for the GitHub user account.
+        [Parameter(
+            Mandatory,
+            ValueFromPipelineByPropertyName
+        )]
+        [string] $Username,
+
+        # The handle for the GitHub user account we want to check if user specified by $Username is following.
+        [Parameter(
+            Mandatory,
+            ValueFromPipelineByPropertyName
+        )]
+        [string] $Follows
+    )
+
+    $inputObject = @{
+        APIEndpoint = "/users/$Username/following/$Follows"
+        Method      = 'GET'
+    }
+
+    try {
+        $null = (Invoke-GitHubAPI @inputObject)
+        return $true
+    } catch {
+        if ($_.Exception.Response.StatusCode.Value__ -eq 404) {
+            return $false
+        } else {
+            throw $_
+        }
+    }
+}

src/GitHub/public/Users/Followers/Add-GitHubUserFollowing.ps1

@@ -0,0 +1,40 @@
+filter Add-GitHubUserFollowing {
+    <#
+        .SYNOPSIS
+        Follow a user
+
+        .DESCRIPTION
+        Note that you'll need to set `Content-Length` to zero when calling out to this endpoint.
+        For more information, see "[HTTP verbs](https://docs.github.com/rest/overview/resources-in-the-rest-api#http-verbs)."
+        Following a user requires the user to be logged in and authenticated with basic auth or OAuth with the `user:follow` scope.
+
+        .EXAMPLE
+        Follow-GitHubUser -Username 'octocat'
+
+        Follows the user with the username 'octocat'.
+
+        .NOTES
+        https://docs.github.com/rest/users/followers#follow-a-user
+
+    #>
+    [OutputType([pscustomobject])]
+    [Alias('Follow-GitHubUser')]
+    [CmdletBinding()]
+    param (
+        # The handle for the GitHub user account.
+        [Parameter(
+            Mandatory,
+            ValueFromPipeline,
+            ValueFromPipelineByPropertyName
+        )]
+        [string] $Username
+    )
+
+    $inputObject = @{
+        APIEndpoint = "/user/following/$Username"
+        Method      = 'PUT'
+    }
+
+    $null = (Invoke-GitHubAPI @inputObject).Response
+
+}

src/GitHub/public/Users/Followers/Get-GitHubUserFollowers.ps1

@@ -0,0 +1,45 @@
+filter Get-GitHubUserFollowers {
+    <#
+        .SYNOPSIS
+        List followers of a given user or the authenticated user
+
+        .DESCRIPTION
+        Lists the people following a given user or the authenticated user.
+
+        .EXAMPLE
+        Get-GitHubUserFollowers
+
+        Gets all followers of the authenticated user.
+
+        .EXAMPLE
+        Get-GitHubUserFollowers -Username 'octocat'
+
+        Gets all followers of the user 'octocat'.
+
+        .NOTES
+        https://docs.github.com/rest/users/followers#list-followers-of-the-authenticated-user
+
+    #>
+    [OutputType([pscustomobject])]
+    [CmdletBinding()]
+    param (
+        # The handle for the GitHub user account.
+        [Parameter(
+            ValueFromPipeline,
+            ValueFromPipelineByPropertyName
+        )]
+        [Alias('login')]
+        [string] $Username,
+
+        # The number of results per page (max 100).
+        [Parameter()]
+        [int] $PerPage = 30
+    )
+
+    if ($Username) {
+        Get-GitHubUserFollowersOfUser -Username $Username -PerPage $PerPage
+    } else {
+        Get-GitHubUserMyFollowers -PerPage $PerPage
+    }
+
+}

src/GitHub/public/Users/Followers/Get-GitHubUserFollowing.ps1

@@ -0,0 +1,46 @@
+filter Get-GitHubUserFollowing {
+    <#
+        .SYNOPSIS
+        List the people a given user or the authenticated user follows
+
+        .DESCRIPTION
+        Lists the people who a given user or the authenticated user follows.
+
+        .EXAMPLE
+        Get-GitHubUserFollowing
+
+        Gets all people the authenticated user follows.
+
+        .EXAMPLE
+        Get-GitHubUserFollowing -Username 'octocat'
+
+        Gets all people that 'octocat' follows.
+
+        .NOTES
+        https://docs.github.com/rest/users/followers#list-the-people-the-authenticated-user-follows
+        https://docs.github.com/rest/users/followers#list-the-people-a-user-follows
+
+    #>
+    [OutputType([pscustomobject])]
+    [CmdletBinding()]
+    param (
+        # The handle for the GitHub user account.
+        [Parameter(
+            ValueFromPipeline,
+            ValueFromPipelineByPropertyName
+        )]
+        [Alias('login')]
+        [string] $Username,
+
+        # The number of results per page (max 100).
+        [Parameter()]
+        [int] $PerPage = 30
+    )
+
+    if ($Username) {
+        Get-GitHubUserFollowingUser -Username $Username -PerPage $PerPage
+    } else {
+        Get-GitHubUserFollowingMe -PerPage $PerPage
+    }
+
+}