🚀 [Feature]: Moving Get-GitHubAppInstallableOrganization into Get-GitHubOrganization (#398)

## Description

This pull request includes breaking changes such as moving a public
function to private, and exposing its functionality through an existing
public function, `Get-GitHubOrganization`.

### Changes to private function `Get-GitHubAppInstallableOrganization`:

* Moved the file from `public` to `private` to reflect its intended
usage.
* Made the `$Context` parameter mandatory, removing the default value of
`(Get-GitHubContext)`.
* Updated the output handling to return a `GitHubOrganization` object
instead of raw API responses, improving type safety.
* Removed a placeholder comment about skipping tests for this function.

### Enhancements to `Get-GitHubOrganization`:

* Added a new parameter set to support fetching organizations by
enterprise slug (`$Enterprise`). This includes marking the `$Enterprise`
parameter as mandatory for the new parameter set.
* Introduced a new `.EXAMPLE` section in the documentation to
demonstrate usage with the enterprise parameter.
* Incorporated a new logic branch in the `switch` statement to handle
enterprise organizations by calling the
`Get-GitHubAppInstallableOrganization` function.

## Type of change

<!-- Use the check-boxes [x] on the options that are relevant. -->

- [ ] 📖 [Docs]
- [ ] 🪲 [Fix]
- [ ] 🩹 [Patch]
- [ ] ⚠️ [Security fix]
- [x] 🚀 [Feature]
- [ ] 🌟 [Breaking change]

## Checklist

<!-- Use the check-boxes [x] on the options that are relevant. -->

- [x] I have performed a self-review of my own code
- [x] I have commented my code, particularly in hard-to-understand areas

Author: MariusStorhaug

examples/Apps/AppManagement.ps1

@@ -2,7 +2,7 @@
 $appIDs = @(
     'Iv1.f26b61bc99e69405'
 )
-$orgs = Get-GitHubAppInstallableOrganization -Enterprise 'msx'
+$orgs = Get-GitHubOrganization -Enterprise 'msx'
 foreach ($org in $orgs) {
     foreach ($appID in $appIDs) {
         Install-GitHubAppOnEnterpriseOrganization -Enterprise msx -Organization $org.login -ClientID $appID -RepositorySelection all

examples/Apps/EnterpriseApps.ps1

@@ -20,7 +20,7 @@ filter Install-GithubApp {
     )
 
     process {
-        $installableOrgs = Get-GitHubAppInstallableOrganization -Enterprise $Enterprise -Debug -Verbose
+        $installableOrgs = Get-GitHubOrganization -Enterprise $Enterprise -Debug -Verbose
         $orgs = $installableOrgs | Where-Object { $_.login -like $organization }
         foreach ($org in $orgs) {
             foreach ($appIDitem in $AppID) {

src/functions/public/Apps/GitHub App/Get-GitHubAppInstallableOrganization.ps1 renamed to src/functions/private/Apps/GitHub Apps/Get-GitHubAppInstallableOrganization.ps1

@@ -27,9 +27,8 @@
         [System.Nullable[int]] $PerPage,
 
         # The context to run the command in. Used to get the details for the API call.
-        # Can be either a string or a GitHubContext object.
-        [Parameter()]
-        [object] $Context = (Get-GitHubContext)
+        [Parameter(Mandatory)]
+        [object] $Context
     )
 
     begin {
@@ -49,13 +48,11 @@
         }
 
         Invoke-GitHubAPI @inputObject | ForEach-Object {
-            Write-Output $_.Response
+            [GitHubOrganization]::new($_.Response)
         }
     }
 
     end {
         Write-Debug "[$stackPath] - End"
     }
 }
-
-#SkipTest:FunctionTest:Will add a test for this function in a future PR

src/functions/public/Organization/Get-GitHubOrganization.ps1

@@ -12,22 +12,27 @@
         .EXAMPLE
         Get-GitHubOrganization
 
-        List organizations for the authenticated user.
+        List all organizations for the authenticated user.
 
         .EXAMPLE
         Get-GitHubOrganization -Username 'octocat'
 
-        List public organizations for the user 'octocat'.
+        List public organizations for a specific user.
 
         .EXAMPLE
         Get-GitHubOrganization -All -Since 142951047
 
-        List organizations, starting with PSModule.
+        List all organizations made after an ID.
 
         .EXAMPLE
         Get-GitHubOrganization -Name 'PSModule'
 
-        Get the organization 'PSModule'.
+        Get a specific organization.
+
+        .EXAMPLE
+        Get-GitHubOrganization -Enterprise 'msx'
+
+        Get the organizations belonging to an Enterprise.
 
         .OUTPUTS
         GitHubOrganization
@@ -36,13 +41,13 @@
         https://psmodule.io/GitHub/Functions/Organization/Get-GitHubOrganization
     #>
     [OutputType([GitHubOrganization])]
-    [CmdletBinding(DefaultParameterSetName = '__AllParameterSets')]
+    [CmdletBinding(DefaultParameterSetName = 'List all organizations for the authenticated user')]
     [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSReviewUnusedParameter', 'All', Justification = 'Required for parameter set')]
     param(
         # The organization name. The name is not case sensitive.
         [Parameter(
             Mandatory,
-            ParameterSetName = 'NamedOrg',
+            ParameterSetName = 'Get a specific organization',
             ValueFromPipeline,
             ValueFromPipelineByPropertyName
         )]
@@ -51,27 +56,34 @@
         # The handle for the GitHub user account.
         [Parameter(
             Mandatory,
-            ParameterSetName = 'NamedUser',
+            ParameterSetName = 'List public organizations for a specific user',
             ValueFromPipelineByPropertyName
         )]
         [Alias('User')]
         [string] $Username,
 
+        # The Enterprise slug to get organizations from.
+        [Parameter(
+            Mandatory,
+            ParameterSetName = 'Get the organizations belonging to an Enterprise',
+            ValueFromPipelineByPropertyName
+        )]
+        [string] $Enterprise,
+
         # List all organizations. Use '-Since' to start at a specific organization ID.
         [Parameter(
             Mandatory,
-            ParameterSetName = 'AllOrg'
+            ParameterSetName = 'List all organizations on the tenant'
         )]
         [switch] $All,
 
         # A organization ID. Only return organizations with an ID greater than this ID.
-        [Parameter(ParameterSetName = 'AllOrg')]
+        [Parameter(ParameterSetName = 'List all organizations on the tenant')]
         [int] $Since = 0,
 
         # The number of results per page (max 100).
-        [Parameter(ParameterSetName = 'AllOrg')]
-        [Parameter(ParameterSetName = 'UserOrg')]
-        [Parameter(ParameterSetName = '__AllParameterSets')]
+        [Parameter(ParameterSetName = 'List all organizations on the tenant')]
+        [Parameter(ParameterSetName = 'List all organizations for the authenticated user')]
         [System.Nullable[int]] $PerPage,
 
         # The context to run the command in. Used to get the details for the API call.
@@ -89,13 +101,16 @@
 
     process {
         switch ($PSCmdlet.ParameterSetName) {
-            'NamedOrg' {
+            'Get a specific organization' {
                 Get-GitHubOrganizationByName -Name $Name -Context $Context
             }
-            'NamedUser' {
+            'List public organizations for a specific user' {
                 Get-GitHubUserOrganization -Username $Username -Context $Context
             }
-            'AllOrg' {
+            'Get the organizations belonging to an Enterprise' {
+                Get-GitHubAppInstallableOrganization -Enterprise $Enterprise -Context $Context
+            }
+            'List all organizations on the tenant' {
                 Get-GitHubAllOrganization -Since $Since -PerPage $PerPage -Context $Context
             }
             default {