[Feature] User - GPG keys - Use the REST API to manage GPG keys of authenticated users (#53)

- Fixes #48
  - Add-GitHubUserGpgKey
  - Remove-GitHubUserGpgKey
  - Get-GitHubUserGpgKey

Author: MariusStorhaug

src/GitHub/private/Users/GPG-Keys/Get-GitHubUserGpgKeyForUser.ps1

@@ -0,0 +1,44 @@
+filter Get-GitHubUserGpgKeyForUser {
+    <#
+        .SYNOPSIS
+        List GPG keys for a user
+
+        .DESCRIPTION
+        Lists the GPG keys for a user. This information is accessible by anyone.
+
+        .EXAMPLE
+        Get-GitHubUserGpgKeyForUser -Username 'octocat'
+
+        Gets all GPG keys for the 'octocat' user.
+
+        .NOTES
+        https://docs.github.com/rest/users/gpg-keys#list-gpg-keys-for-a-user
+
+    #>
+    [OutputType([pscustomobject])]
+    [CmdletBinding()]
+    param (
+        # The handle for the GitHub user account.
+        [Parameter(
+            Mandatory,
+            ValueFromPipelineByPropertyName
+        )]
+        [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/gpg_keys"
+        Method      = 'GET'
+        Body        = $body
+    }
+
+    (Invoke-GitHubAPI @inputObject).Response
+
+}

src/GitHub/private/Users/GPG-Keys/Get-GitHubUserMyGpgKey.ps1

@@ -0,0 +1,37 @@
+filter Get-GitHubUserMyGpgKey {
+    <#
+        .SYNOPSIS
+        List GPG keys for the authenticated user
+
+        .DESCRIPTION
+        Lists the current user's GPG keys.
+        Requires that you are authenticated via Basic Auth or via OAuth with at least `read:gpg_key` [scope](https://docs.github.com/apps/building-oauth-apps/understanding-scopes-for-oauth-apps/).
+
+        .EXAMPLE
+        Get-GitHubUserMyGpgKey
+
+        Gets all GPG keys for the authenticated user.
+
+        .NOTES
+        https://docs.github.com/rest/users/gpg-keys#list-gpg-keys-for-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/gpg_keys'
+        Method      = 'GET'
+        Body        = $body
+    }
+
+    (Invoke-GitHubAPI @inputObject).Response
+
+}

src/GitHub/private/Users/GPG-Keys/Get-GitHubUserMyGpgKeyById.ps1

@@ -0,0 +1,37 @@
+filter Get-GitHubUserMyGpgKeyById {
+    <#
+        .SYNOPSIS
+        Get a GPG key for the authenticated user
+
+        .DESCRIPTION
+        View extended details for a single GPG key.
+        Requires that you are authenticated via Basic Auth or via OAuth with at least `read:gpg_key` [scope](https://docs.github.com/apps/building-oauth-apps/understanding-scopes-for-oauth-apps/).
+
+        .EXAMPLE
+        Get-GitHubUserMyGpgKeyById -GpgKeyID '4AEE18F83AFDEB23'
+
+        Gets the GPG key with ID '4AEE18F83AFDEB23' for the authenticated user.
+
+        .NOTES
+        https://docs.github.com/rest/users/gpg-keys#get-a-gpg-key-for-the-authenticated-user
+
+    #>
+    [OutputType([pscustomobject])]
+    [CmdletBinding()]
+    param (
+        # The ID of the GPG key.
+        [Parameter(
+            Mandatory
+        )]
+        [Alias('gpg_key_id')]
+        [string] $ID
+    )
+
+    $inputObject = @{
+        APIEndpoint = "/user/gpg_keys/$ID"
+        Method      = 'GET'
+    }
+
+    (Invoke-GitHubAPI @inputObject).Response
+
+}

src/GitHub/public/Users/GPG-Keys/Add-GitHubUserGpgKey.ps1

@@ -0,0 +1,50 @@
+filter Add-GitHubUserGpgKey {
+    <#
+        .SYNOPSIS
+        Create a GPG key for the authenticated user
+
+        .DESCRIPTION
+        Adds a GPG key to the authenticated user's GitHub account.
+        Requires that you are authenticated via Basic Auth, or OAuth with at least `write:gpg_key` [scope](https://docs.github.com/apps/building-oauth-apps/understanding-scopes-for-oauth-apps/).
+
+        .EXAMPLE
+        Add-GitHubUserGpgKey -Name 'GPG key for GitHub' -ArmoredPublicKey '-----BEGIN PGP PUBLIC KEY BLOCK-----\nVersion: GnuPG v1\n\nmQINBFnZ2ZIBEADQ2Z7Z7\n-----END PGP PUBLIC KEY BLOCK-----'
+
+        Adds a GPG key to the authenticated user's GitHub account.
+
+        .NOTES
+        https://docs.github.com/rest/users/gpg-keys#create-a-gpg-key-for-the-authenticated-user
+
+    #>
+    [OutputType([pscustomobject])]
+    [CmdletBinding()]
+    param (
+        # A descriptive name for the new key.
+        [Parameter(
+            Mandatory,
+            ValueFromPipeline,
+            ValueFromPipelineByPropertyName
+        )]
+        [string] $Name,
+
+        # A GPG key in ASCII-armored format.
+        [Parameter(
+            Mandatory,
+            ValueFromPipelineByPropertyName
+        )]
+        [Alias('armored_public_key')]
+        [string] $ArmoredPublicKey
+
+    )
+
+    $body = $PSBoundParameters | ConvertFrom-HashTable | ConvertTo-HashTable -NameCasingStyle snake_case
+
+    $inputObject = @{
+        APIEndpoint = "/user/gpg_keys"
+        Method      = 'POST'
+        Body        = $body
+    }
+
+    (Invoke-GitHubAPI @inputObject).Response
+
+}

src/GitHub/public/Users/GPG-Keys/Get-GitHubUserGpgKey.ps1

@@ -0,0 +1,56 @@
+filter Get-GitHubUserGpgKey {
+    <#
+        .SYNOPSIS
+        List GPG keys for a given user or the authenticated user
+
+        .DESCRIPTION
+        Lists a given user's or the current user's GPG keys.
+
+        .EXAMPLE
+        Get-GitHubUserGpgKey
+
+        Gets all GPG keys for the authenticated user.
+
+        .EXAMPLE
+        Get-GitHubUserGpgKey -Username 'octocat'
+
+        Gets all GPG keys for the 'octocat' user.
+
+        .NOTES
+        https://docs.github.com/rest/users/gpg-keys#list-gpg-keys-for-the-authenticated-user
+
+    #>
+    [OutputType([pscustomobject])]
+    [CmdletBinding()]
+    param (
+        # The handle for the GitHub user account.
+        [Parameter(
+            Mandatory,
+            ValueFromPipeline,
+            ValueFromPipelineByPropertyName,
+            ParameterSetName = 'Username'
+        )]
+        [string] $Username,
+
+        # The ID of the GPG key.
+        [Parameter(
+            ParameterSetName = 'Me'
+        )]
+        [Alias('gpg_key_id')]
+        [string] $ID,
+
+        # The number of results per page (max 100).
+        [Parameter()]
+        [int] $PerPage = 30
+    )
+
+    if ($Username) {
+        Get-GitHubUserGpgKeyForUser -Username $Username -PerPage $PerPage
+    } else {
+        if ($ID) {
+            Get-GitHubUserMyGpgKeyById -ID $ID
+        } else {
+            Get-GitHubUserMyGpgKey -PerPage $PerPage
+        }
+    }
+}

src/GitHub/public/Users/GPG-Keys/Remove-GitHubUserGpgKey.ps1

@@ -0,0 +1,37 @@
+filter Remove-GitHubUserGpgKey {
+    <#
+        .SYNOPSIS
+        Delete a GPG key for the authenticated user
+
+        .DESCRIPTION
+        Removes a GPG key from the authenticated user's GitHub account.
+        Requires that you are authenticated via Basic Auth or via OAuth with at least `admin:gpg_key` [scope](https://docs.github.com/apps/building-oauth-apps/understanding-scopes-for-oauth-apps/).
+
+        .EXAMPLE
+        Remove-GitHubUserGpgKey -ID '1234567'
+
+        Gets the GPG key with ID '1234567' for the authenticated user.
+
+        .NOTES
+        https://docs.github.com/rest/users/gpg-keys#delete-a-gpg-key-for-the-authenticated-user
+
+    #>
+    [OutputType([pscustomobject])]
+    [CmdletBinding()]
+    param (
+        # The ID of the GPG key.
+        [Parameter(
+            Mandatory
+        )]
+        [Alias('gpg_key_id')]
+        [string] $ID
+    )
+
+    $inputObject = @{
+        APIEndpoint = "/user/gpg_keys/$ID"
+        Method      = 'DELETE'
+    }
+
+    $null = (Invoke-GitHubAPI @inputObject).Response
+
+}

tools/utilities/GitHubAPI.ps1

@@ -21,8 +21,8 @@ $response = Invoke-RestMethod -Uri $APIDocURI -Method Get
 # @{n = 'PUT'; e = { (($_.value.psobject.Properties.Name) -contains 'PUT') } }, `
 # @{n = 'PATCH'; e = { (($_.value.psobject.Properties.Name) -contains 'PATCH') } } | Format-Table
 
-$path = '/users/{username}/following/{target_user}'
-$method = 'GET'
+$path = '/user/gpg_keys/{gpg_key_id}'
+$method = 'DELETE'
 $response.paths.$path.$method
 $response.paths.$path.$method.tags | clip                             # -> Namespace/foldername
 $response.paths.$path.$method.operationId | clip                      # -> FunctionName