Skip to content

Commit 3367f90

Browse files
MariusStorhaugMariusStorhaug
authored
🚀 [Feature]: Add class for GitHubApp and GitHubAppInstallation (#406)
## Description This pull request introduces significant enhancements to the GitHub Apps module by adding new classes, improving type safety, and refining existing functions. The changes focus on creating structured representations for GitHub Apps and their installations, updating function outputs to use these new types, and improving parameter handling for better usability and clarity. ### New Classes for GitHub Apps and Installations: * [`src/classes/public/App/GitHubApp.ps1`](diffhunk://#diff-067422a4a7efa7c966720b01cb15b3868f47b408676fd32b13c0d0a5fd13f28fR1-R66): Introduced the `GitHubApp` class to encapsulate properties and methods for GitHub Apps, including `ID`, `ClientID`, `Slug`, `Permissions`, and `Events`. This improves type safety and enables structured handling of app data. * [`src/classes/public/App/GitHubAppInstallation.ps1`](diffhunk://#diff-c1442a9fa3e51d2f0bf378039e97400122a24423d72d534112ca6f7c06a5ffaeR1-R63): Added the `GitHubAppInstallation` class to represent app installations, including `ID`, `Target`, `Permissions`, and `CreatedAt`. This facilitates better organization and manipulation of installation data. ### Updates to Function Outputs: * [`src/functions/private/Apps/GitHub Apps/Get-GitHubAppByName.ps1`](diffhunk://#diff-2446812fa850e0b15e44ea484a0ef116efbe4b5d7e22b74960faf084b4015256L17-R17): Changed output type from `[pscustomobject]` to `[GitHubApp]` and updated the response handling to instantiate `GitHubApp` objects. [[1]](diffhunk://#diff-2446812fa850e0b15e44ea484a0ef116efbe4b5d7e22b74960faf084b4015256L17-R17) [[2]](diffhunk://#diff-2446812fa850e0b15e44ea484a0ef116efbe4b5d7e22b74960faf084b4015256L46-R46) * [`src/functions/private/Apps/GitHub Apps/Get-GitHubAppInstallationForAuthenticatedApp.ps1`](diffhunk://#diff-f58f23b4edc1de29c735a7576182208d9f0d4908650818560c1d5a20e4a59674R17-R29): Updated output type to `[GitHubAppInstallation[]]` and modified response processing to create instances of `GitHubAppInstallation`. [[1]](diffhunk://#diff-f58f23b4edc1de29c735a7576182208d9f0d4908650818560c1d5a20e4a59674R17-R29) [[2]](diffhunk://#diff-f58f23b4edc1de29c735a7576182208d9f0d4908650818560c1d5a20e4a59674R45-R52) * [`src/functions/private/Apps/GitHub Apps/Get-GitHubEnterpriseOrganizationAppInstallation.ps1`](diffhunk://#diff-cb918ad0c83be9fde80efae340f437639173ba82a5a363ef7b1a9be93e05dfd5L19-R19): Updated output type to `[GitHubAppInstallation]` and adjusted response handling for better type safety. [[1]](diffhunk://#diff-cb918ad0c83be9fde80efae340f437639173ba82a5a363ef7b1a9be93e05dfd5L19-R19) [[2]](diffhunk://#diff-cb918ad0c83be9fde80efae340f437639173ba82a5a363ef7b1a9be93e05dfd5L61-R61) ### Refinements to Parameter Handling: * [`src/functions/public/Apps/GitHub App/Get-GitHubApp.ps1`](diffhunk://#diff-eb4b0ed1f801228094dc7d155d3b2cd9a7a417d294ead8583bdfa87e455efcd5L27-R36): Improved parameter set names for clarity, such as renaming `'BySlug'` to `'Get an app by slug'`. Added alias `Slug` for the `Name` parameter to enhance usability. [[1]](diffhunk://#diff-eb4b0ed1f801228094dc7d155d3b2cd9a7a417d294ead8583bdfa87e455efcd5L27-R36) [[2]](diffhunk://#diff-eb4b0ed1f801228094dc7d155d3b2cd9a7a417d294ead8583bdfa87e455efcd5L53-R53) * [`src/functions/public/Apps/GitHub App Installations/Get-GitHubAppInstallation.ps1`](diffhunk://#diff-9ca965372ef6314e8f8759ce87dedff3c8a0d216fe06fda41e0fb38b89722dfeL14-R39): Refined parameter sets to clearly differentiate between listing installations for enterprises, organizations, and authenticated apps. [[1]](diffhunk://#diff-9ca965372ef6314e8f8759ce87dedff3c8a0d216fe06fda41e0fb38b89722dfeL14-R39) [[2]](diffhunk://#diff-9ca965372ef6314e8f8759ce87dedff3c8a0d216fe06fda41e0fb38b89722dfeL55-R74) ### Adjustments to Existing Classes: * [`src/classes/public/Owner/GitHubOwner.ps1`](diffhunk://#diff-41f600a6b5b0e373d0e53465e24c629e95b33f9864c206542e843fc2a269bcabL78-R84): Updated property mappings to handle both `slug` and `login` for `Name` and added fallback for `Blog` using `website_url`. ### Context Improvements: * [`src/functions/private/Auth/Context/Set-GitHubContext.ps1`](diffhunk://#diff-600a257f8ea7acdd36413aef2daf597ab69dd5bb3c17ec7d6fed83e15f0af1d7L81-R81): Updated context object properties to use the new `GitHubApp` class, ensuring consistency and type safety across app-related context data. [[1]](diffhunk://#diff-600a257f8ea7acdd36413aef2daf597ab69dd5bb3c17ec7d6fed83e15f0af1d7L81-R81) [[2]](diffhunk://#diff-600a257f8ea7acdd36413aef2daf597ab69dd5bb3c17ec7d6fed83e15f0af1d7L125-R133) ## 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
1 parent 413bc5c commit 3367f90

18 files changed

+302
-94
lines changed

‎examples/Apps/EnterpriseApps.ps1

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -20,11 +20,11 @@ filter Install-GithubApp {
2020
)
2121

2222
process {
23-
$installableOrgs = Get-GitHubOrganization -Enterprise $Enterprise -Debug -Verbose
23+
$installableOrgs = Get-GitHubOrganization -Enterprise $Enterprise
2424
$orgs = $installableOrgs | Where-Object { $_.login -like $organization }
2525
foreach ($org in $orgs) {
2626
foreach ($appIDitem in $AppID) {
27-
Install-GitHubAppOnEnterpriseOrganization -Enterprise $Enterprise -Organization $org.login -ClientID $appIDitem -RepositorySelection all | ForEach-Object {
27+
Install-GitHubApp -Enterprise $Enterprise -Organization $org.login -ClientID $appIDitem -RepositorySelection all | ForEach-Object {
2828
[PSCustomObject]@{
2929
Organization = $org.login
3030
AppID = $appIDitem
@@ -35,6 +35,6 @@ filter Install-GithubApp {
3535
}
3636
}
3737

38-
$appIDs | Install-GitHubApp -Organization $organization -Debug -Verbose
38+
$appIDs | Install-GitHubApp -Organization $organization
3939

4040
$installation = Get-GitHubAppInstallation

‎src/classes/public/App/GitHubApp.ps1

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
class GitHubApp : GitHubNode {
2+
# The unique ID of the app
3+
[System.Nullable[UInt64]] $ID
4+
5+
# The Client ID of the app
6+
[string] $ClientID
7+
8+
# The App ID of the app
9+
[System.Nullable[UInt64]] $AppID
10+
11+
# The Slug of the app
12+
[string] $Slug
13+
14+
# The node_id of the app
15+
[string] $NodeID
16+
17+
# The owner of the app.
18+
[GitHubOwner] $Owner
19+
20+
# The name of the app
21+
[string] $Name
22+
23+
# The description of the app
24+
[string] $Description
25+
26+
# The external URL of the app
27+
[string] $ExternalUrl
28+
29+
# The HTML URL of the app
30+
[string] $Url
31+
32+
# The creation date of the app
33+
[System.Nullable[datetime]] $CreatedAt
34+
35+
# The last update date of the app
36+
[System.Nullable[datetime]] $UpdatedAt
37+
38+
# The permissions that the app is requesting.
39+
[pscustomobject] $Permissions
40+
41+
# The events that the app is subscribing to on its target.
42+
[string[]] $Events
43+
44+
# The number of installations
45+
[System.Nullable[int]] $Installations
46+
47+
GitHubApp() {}
48+
49+
GitHubApp([object]$Object) {
50+
$this.ID = $Object.id
51+
$this.ClientID = $Object.client_id
52+
$this.AppID = $Object.app_id
53+
$this.Slug = $Object.app_slug ?? $Object.slug
54+
$this.NodeID = $Object.node_id
55+
$this.Owner = [GitHubOwner]::new($Object.owner)
56+
$this.Name = $Object.name
57+
$this.Description = $Object.description
58+
$this.ExternalUrl = $Object.external_url
59+
$this.Url = $Object.html_url
60+
$this.CreatedAt = $Object.created_at
61+
$this.UpdatedAt = $Object.updated_at
62+
$this.Permissions = $Object.permissions
63+
$this.Events = , ($Object.events)
64+
$this.Installations = $Object.installations_count
65+
}
66+
}

‎src/classes/public/App/GitHubAppInstallation.ps1

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
class GitHubAppInstallation {
2+
# The installation ID on the target.
3+
[System.Nullable[UInt64]] $ID
4+
5+
# The app that is installed.
6+
[GitHubApp] $App
7+
8+
# The target of the installation.
9+
[GitHubOwner] $Target
10+
11+
# The type of target.
12+
[string] $Type
13+
14+
# The type of repository selection.
15+
[string] $RepositorySelection
16+
17+
# The permissions that the app has on the target.
18+
[pscustomobject] $Permissions
19+
20+
# The events that the app is subscribing to.
21+
[string[]] $Events
22+
23+
# The file paths that the app has access to.
24+
[string[]] $FilePaths
25+
26+
# The creation date of the installation.
27+
# Example: 2008-01-14T04:33:35Z
28+
[System.Nullable[datetime]] $CreatedAt
29+
30+
# The last update date of the installation.
31+
# Example: 2008-01-14T04:33:35Z
32+
[System.Nullable[datetime]] $UpdatedAt
33+
34+
# The date the installation was suspended.
35+
# Example: 2008-01-14T04:33:35Z
36+
[System.Nullable[datetime]] $SuspendedAt
37+
38+
# The account that suspended the installation.
39+
[GitHubUser] $SuspendedBy
40+
41+
GitHubAppInstallation() {}
42+
43+
GitHubAppInstallation([PSCustomObject]$Object) {
44+
$this.ID = $Object.id
45+
$this.App = [GitHubApp]::new(
46+
[PSCustomObject]@{
47+
client_id = $Object.client_id
48+
app_id = $Object.app_id
49+
app_slug = $Object.app_slug
50+
}
51+
)
52+
$this.Target = [GitHubOwner]::new($Object.account)
53+
$this.Type = $Object.target_type
54+
$this.RepositorySelection = $Object.repository_selection
55+
$this.Permissions = $Object.permissions
56+
$this.Events = , ($Object.events)
57+
$this.FilePaths = $Object.single_file_paths
58+
$this.CreatedAt = $Object.created_at
59+
$this.UpdatedAt = $Object.updated_at
60+
$this.SuspendedAt = $Object.suspended_at
61+
$this.SuspendedBy = [GitHubUser]::new($Object.suspended_by)
62+
}
63+
}

‎src/classes/public/Owner/GitHubOwner.ps1

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -75,13 +75,13 @@
7575
$this.NodeID = $Object.node_id
7676

7777
# From GitHubOwner
78-
$this.Name = $Object.login
78+
$this.Name = $Object.slug ?? $Object.login
7979
$this.DisplayName = $Object.name
8080
$this.AvatarUrl = $Object.avatar_url
8181
$this.Url = $Object.html_url
8282
$this.Type = $Object.type
8383
$this.Company = $Object.company
84-
$this.Blog = $Object.blog
84+
$this.Blog = $Object.website_url ?? $Object.blog
8585
$this.Location = $Object.location
8686
$this.Email = $Object.email
8787
$this.TwitterUsername = $Object.twitter_username

‎src/functions/private/Apps/GitHub Apps/Get-GitHubAppByName.ps1

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@
1414
.NOTES
1515
[Get an app](https://docs.github.com/rest/apps/apps#get-an-app)
1616
#>
17-
[OutputType([pscustomobject])]
17+
[OutputType([GitHubApp])]
1818
[CmdletBinding()]
1919
param(
2020
# The AppSlug is just the URL-friendly name of a GitHub App.
@@ -43,7 +43,7 @@
4343
}
4444

4545
Invoke-GitHubAPI @inputObject | ForEach-Object {
46-
Write-Output $_.Response
46+
[GitHubApp]::new($_.Response)
4747
}
4848
}
4949
end {

‎src/functions/private/Apps/GitHub Apps/Get-GitHubAppInstallableOrganization.ps1

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,9 +13,13 @@
1313
.EXAMPLE
1414
Get-GitHubAppInstallableOrganization -Enterprise 'msx'
1515
16+
.OUTPUTS
17+
GitHubOrganization[]
18+
1619
.LINK
1720
https://psmodule.io/GitHub/Functions/Apps/GitHub%20App/Get-GitHubAppInstallableOrganization
1821
#>
22+
[OutputType([GitHubOrganization[]])]
1923
[CmdletBinding()]
2024
param(
2125
# The enterprise slug or ID.

‎src/functions/private/Apps/GitHub Apps/Get-GitHubAppInstallationForAuthenticatedApp.ps1

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,11 +14,19 @@
1414
1515
List installations for the authenticated app.
1616
17+
.OUTPUTS
18+
GitHubAppInstallation[]
19+
1720
.NOTES
1821
[List installations for the authenticated app](https://docs.github.com/rest/apps/apps#list-installations-for-the-authenticated-app)
1922
#>
23+
[OutputType([GitHubAppInstallation])]
2024
[CmdletBinding()]
2125
param(
26+
# The number of results per page (max 100).
27+
[Parameter()]
28+
[System.Nullable[int]] $PerPage,
29+
2230
# The context to run the command in. Used to get the details for the API call.
2331
[Parameter(Mandatory)]
2432
[object] $Context
@@ -34,11 +42,14 @@
3442
$inputObject = @{
3543
Context = $Context
3644
APIEndpoint = '/app/installations'
45+
PerPage = $PerPage
3746
Method = 'GET'
3847
}
3948

4049
Invoke-GitHubAPI @inputObject | ForEach-Object {
41-
Write-Output $_.Response
50+
$_.Response | ForEach-Object {
51+
[GitHubAppInstallation]::new($_)
52+
}
4253
}
4354
}
4455

‎src/functions/private/Apps/GitHub Apps/Get-GitHubAuthenticatedApp.ps1

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@
2020
.NOTES
2121
[Get the authenticated app](https://docs.github.com/rest/apps/apps#get-an-app)
2222
#>
23-
[OutputType([pscustomobject])]
23+
[OutputType([GitHubApp])]
2424
[CmdletBinding()]
2525
param(
2626
# The context to run the command in. Used to get the details for the API call.
@@ -42,7 +42,7 @@
4242
}
4343

4444
Invoke-GitHubAPI @inputObject | ForEach-Object {
45-
Write-Output $_.Response
45+
[GitHubApp]::new($_.Response)
4646
}
4747
}
4848
end {

‎src/functions/private/Apps/GitHub Apps/Get-GitHubEnterpriseOrganizationAppInstallation.ps1

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@
1616
.NOTES
1717
[List GitHub Apps installed on an enterprise-owned organization]()
1818
#>
19-
[OutputType([pscustomobject])]
19+
[OutputType([GitHubAppInstallation])]
2020
[CmdletBinding()]
2121
param(
2222
# The enterprise slug or ID.
@@ -58,7 +58,7 @@
5858
}
5959

6060
Invoke-GitHubAPI @inputObject | ForEach-Object {
61-
Write-Output $_.Response
61+
[GitHubAppInstallation]::new($_.Response)
6262
}
6363
}
6464

‎src/functions/private/Apps/GitHub Apps/Get-GitHubOrganizationAppInstallation.ps1

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@
1515
.NOTES
1616
[List app installations for an organization](https://docs.github.com/rest/orgs/orgs#list-app-installations-for-an-organization)
1717
#>
18-
[OutputType([pscustomobject])]
18+
[OutputType([GitHubAppInstallation])]
1919
[CmdletBinding()]
2020
param(
2121
# The organization name. The name is not case sensitive.
@@ -50,7 +50,9 @@
5050
}
5151

5252
Invoke-GitHubAPI @inputObject | ForEach-Object {
53-
Write-Output $_.Response.installations
53+
$_.Response.installations | ForEach-Object {
54+
[GitHubAppInstallation]::new($_)
55+
}
5456
}
5557
}
5658

0 commit comments

Comments
 (0)