[Feature] User - Email - Use the REST API to manage email addresses of authenticated users

src/GitHub/private/Users/Emails/Get-GitHubUserAllEmail.ps1

@@ -0,0 +1,36 @@
+filter Get-GitHubUserAllEmail {
+    <#
+        .SYNOPSIS
+        List email addresses for the authenticated user
+
+        .DESCRIPTION
+        Lists all of your email addresses, and specifies which one is visible to the public. This endpoint is accessible with the `user:email` scope.
+
+        .EXAMPLE
+        Get-GitHubUserAllEmail
+
+        Gets all email addresses for the authenticated user.
+
+        .NOTES
+        https://docs.github.com/rest/users/emails#list-email-addresses-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/emails"
+        Method      = 'GET'
+        Body        = $body
+    }
+
+    (Invoke-GitHubAPI @inputObject).Response
+
+}

src/GitHub/private/Users/Emails/Get-GitHubUserPublicEmail.ps1

@@ -0,0 +1,36 @@
+filter Get-GitHubUserPublicEmail {
+    <#
+        .SYNOPSIS
+        List public email addresses for the authenticated user
+
+        .DESCRIPTION
+        Lists your publicly visible email address, which you can set with the [Set primary email visibility for the authenticated user](https://docs.github.com/rest/users/emails#set-primary-email-visibility-for-the-authenticated-user) endpoint. This endpoint is accessible with the `user:email` scope.
+
+        .EXAMPLE
+        Get-GitHubUserPublicEmail
+
+        Gets all public email addresses for the authenticated user.
+
+        .NOTES
+        https://docs.github.com/rest/users/emails#list-public-email-addresses-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/public_emails"
+        Method      = 'GET'
+        Body        = $body
+    }
+
+    (Invoke-GitHubAPI @inputObject).Response
+
+}

src/GitHub/public/Users/Emails/Add-GitHubUserEmail.ps1

@@ -0,0 +1,43 @@
+filter Add-GitHubUserEmail {
+    <#
+        .SYNOPSIS
+        Add an email address for the authenticated user
+
+        .DESCRIPTION
+        This endpoint is accessible with the `user` scope.
+
+        .EXAMPLE
+        Add-GitHubUserEmail -Emails 'octocat@github.com','firstname.lastname@work.com'
+
+        Adds the email addresses 'octocat@github.com' and 'firstname.lastname@work.com' to the authenticated user's account.
+
+        .NOTES
+        https://docs.github.com/rest/users/emails#add-an-email-address-for-the-authenticated-user
+
+    #>
+    [OutputType([pscustomobject])]
+    [CmdletBinding()]
+    param (
+        # Adds one or more email addresses to your GitHub account.
+        # Must contain at least one email address.
+        # Note: Alternatively, you can pass a single email address or an array of emails addresses directly,
+        # but we recommend that you pass an object using the emails key.
+        [Parameter(
+            Mandatory,
+            ValueFromPipeline,
+            ValueFromPipelineByPropertyName
+        )]
+        [string[]] $Emails
+    )
+
+    $body = $PSBoundParameters | ConvertFrom-HashTable | ConvertTo-HashTable -NameCasingStyle snake_case
+
+    $inputObject = @{
+        APIEndpoint = "/user/emails"
+        Method      = 'POST'
+        Body        = $body
+    }
+
+    (Invoke-GitHubAPI @inputObject).Response
+
+}

src/GitHub/public/Users/Emails/Get-GitHubUserEmail.ps1

@@ -0,0 +1,42 @@
+filter Get-GitHubUserEmail {
+    <#
+        .SYNOPSIS
+        List email addresses for the authenticated user
+
+        .DESCRIPTION
+        Lists all of your email addresses, and specifies which one is visible to the public. This endpoint is accessible with the `user:email` scope.
+        Specifying '-Public' will return only the publicly visible email address, which you can set with the [Set primary email visibility for the authenticated user](https://docs.github.com/rest/users/emails#set-primary-email-visibility-for-the-authenticated-user) endpoint.
+
+        .EXAMPLE
+        Get-GitHubUserEmail
+
+        Gets all email addresses for the authenticated user.
+
+        .EXAMPLE
+        Get-GitHubUserEmail -Public
+
+        Gets the publicly visible email address for the authenticated user.
+
+        .NOTES
+        https://docs.github.com/rest/users/emails#list-email-addresses-for-the-authenticated-user
+        https://docs.github.com/en/rest/users/emails#list-public-email-addresses-for-the-authenticated-user
+
+    #>
+    [OutputType([pscustomobject])]
+    [CmdletBinding()]
+    param (
+        # The number of results per page (max 100).
+        [Parameter()]
+        [int] $PerPage = 30,
+
+        [Parameter()]
+        [switch] $Public
+    )
+
+    if ($Public) {
+        Get-GitHubUserPublicEmail -PerPage $PerPage
+    } else {
+        Get-GitHubUserAllEmail -PerPage $PerPage
+    }
+
+}

src/GitHub/public/Users/Emails/Remove-GitHubUserEmail.ps1

@@ -0,0 +1,40 @@
+filter Remove-GitHubUserEmail {
+    <#
+        .SYNOPSIS
+        Delete an email address for the authenticated user
+
+        .DESCRIPTION
+        This endpoint is accessible with the `user` scope.
+
+        .EXAMPLE
+        Remove-GitHubUserEmail -Emails 'octocat@github.com','firstname.lastname@work.com'
+
+        Removes the email addresses 'octocat@github.com' and 'firstname.lastname@work.com' from the authenticated user's account.
+
+        .NOTES
+        https://docs.github.com/rest/users/emails#delete-an-email-address-for-the-authenticated-user
+
+    #>
+    [OutputType([pscustomobject])]
+    [CmdletBinding()]
+    param (
+        # Email addresses associated with the GitHub user account.
+        [Parameter(
+            Mandatory,
+            ValueFromPipeline,
+            ValueFromPipelineByPropertyName
+        )]
+        [string[]] $Emails
+    )
+
+    $body = $PSBoundParameters | ConvertFrom-HashTable | ConvertTo-HashTable -NameCasingStyle snake_case
+
+    $inputObject = @{
+        APIEndpoint = "/user/emails"
+        Method      = 'DELETE'
+        Body        = $body
+    }
+
+    $null = (Invoke-GitHubAPI @inputObject).Response
+
+}

src/GitHub/public/Users/Emails/Set-GitHubUserEmailVisibility.ps1

@@ -0,0 +1,46 @@
+filter Set-GitHubUserEmailVisibility {
+    <#
+        .SYNOPSIS
+        Set primary email visibility for the authenticated user
+
+        .DESCRIPTION
+        Sets the visibility for your primary email addresses.
+
+        .EXAMPLE
+        Set-GitHubUserEmailVisibility -Visibility public
+
+        Sets the visibility for your primary email addresses to public.
+
+        .EXAMPLE
+        Set-GitHubUserEmailVisibility -Visibility private
+
+        Sets the visibility for your primary email addresses to private.
+
+        .NOTES
+        https://docs.github.com/rest/users/emails#set-primary-email-visibility-for-the-authenticated-user
+
+    #>
+    [OutputType([pscustomobject])]
+    [CmdletBinding()]
+    param (
+        # Denotes whether an email is publicly visible.
+        [Parameter(
+            Mandatory,
+            ValueFromPipeline,
+            ValueFromPipelineByPropertyName
+        )]
+        [ValidateSet('public', 'private')]
+        [string] $Visibility
+    )
+
+    $body = $PSBoundParameters | ConvertFrom-HashTable | ConvertTo-HashTable -NameCasingStyle snake_case
+
+    $inputObject = @{
+        APIEndpoint = "/user/email/visibility"
+        Method      = 'PATCH'
+        Body        = $body
+    }
+
+    (Invoke-GitHubAPI @inputObject).Response
+
+}

tools/utilities/GitHubAPI.ps1

@@ -4,25 +4,25 @@ $Dereferenced = 'descriptions/api.github.com/dereferenced/api.github.com.deref.j
 $APIDocURI = $APIDocURI + $Bundled
 $response = Invoke-RestMethod -Uri $APIDocURI -Method Get
 
-$response.info          # API name = GitHub REST API
-$response.openapi       # Spec version = 3.0.3
-$response.servers       # API URL = api.github.com
-$response.externalDocs  # API docs URL = docs.github.com/rest
-$response.components    # Type specs
-$response.paths         # API endpoints # -> Namespaces, PascalCase!
-$response.tags          # API categories
-$response.'x-webhooks'  # Webhooks/event docs
+# $response.info          # API name = GitHub REST API
+# $response.openapi       # Spec version = 3.0.3
+# $response.servers       # API URL = api.github.com
+# $response.externalDocs  # API docs URL = docs.github.com/rest
+# $response.components    # Type specs
+# $response.paths         # API endpoints # -> Namespaces, PascalCase!
+# $response.tags          # API categories
+# $response.'x-webhooks'  # Webhooks/event docs
 
-$response.paths.psobject.Properties | Select-Object `
-    Name, `
-@{n = 'Get'; e = { (($_.value.psobject.Properties.Name) -contains 'Get') } }, `
-@{n = 'Post'; e = { (($_.value.psobject.Properties.Name) -contains 'Post') } }, `
-@{n = 'Delete'; e = { (($_.value.psobject.Properties.Name) -contains 'Delete') } }, `
-@{n = 'PUT'; e = { (($_.value.psobject.Properties.Name) -contains 'PUT') } }, `
-@{n = 'PATCH'; e = { (($_.value.psobject.Properties.Name) -contains 'PATCH') } } | Format-Table
+# $response.paths.psobject.Properties | Select-Object `
+#     Name, `
+# @{n = 'Get'; e = { (($_.value.psobject.Properties.Name) -contains 'Get') } }, `
+# @{n = 'Post'; e = { (($_.value.psobject.Properties.Name) -contains 'Post') } }, `
+# @{n = 'Delete'; e = { (($_.value.psobject.Properties.Name) -contains 'Delete') } }, `
+# @{n = 'PUT'; e = { (($_.value.psobject.Properties.Name) -contains 'PUT') } }, `
+# @{n = 'PATCH'; e = { (($_.value.psobject.Properties.Name) -contains 'PATCH') } } | Format-Table
 
-$path = '/orgs/{org}/blocks/{username}'
-$method = 'delete'
+$path = '/user/email/visibility'
+$method = 'patch'
 $response.paths.$path.$method
 $response.paths.$path.$method.tags | clip                             # -> Namespace/foldername
 $response.paths.$path.$method.operationId | clip                      # -> FunctionName

tools/utilities/Local-Testing.ps1

@@ -38,7 +38,6 @@ $format = "yyyy-MM-dd HH:mm:ss 'UTC'"
 $date = [datetime]::ParseExact($str, $format, $null)
 $date
 
-
 Get-GitHubOrganization | Select-Object Name, login, id
 Get-GitHubOrganization -OrganizationName 'PowerShell'
 Get-GitHubOrganization -OrganizationName 'PSModule'
@@ -63,3 +62,7 @@ Set-GitHubUser -Hireable $true | Select-Object login, hireable
 Set-GitHubUser -Hireable $false | Select-Object login, hireable
 
 Add-GitHubUserSocials -AccountUrls 'https://www.github.com/MariusStorhaug'
+
+Get-GitHubUserEmail
+Add-GitHubUserEmail -Emails 'octocat@psmodule.io'
+Remove-GitHubUserEmail -Emails 'octocat@psmodule.io'