From 0c8357495e712f5d4a53864dc72f0f8f852020a1 Mon Sep 17 00:00:00 2001 From: Hannes Papenberg Date: Thu, 12 Nov 2026 22:05:50 +0100 Subject: [PATCH] Add the Apps API package Adds Joomla\Github\Package\Apps ($github->apps) with the sub-packages Apps\Installations, Apps\Marketplace, Apps\OauthApplications and Apps\Webhooks, covering all 37 operations of the GitHub REST apps category. docs/apps.md explains which credential (JWT, client ID/secret, token) each operation needs. Co-Authored-By: Claude Opus 5.5 --- Tests/Package/Apps/InstallationsTest.php | 250 +++++++++ Tests/Package/Apps/MarketplaceTest.php | 328 +++++++++++ Tests/Package/Apps/OauthApplicationsTest.php | 188 +++++++ Tests/Package/Apps/WebhooksTest.php | 223 ++++++++ Tests/Package/AppsTest.php | 544 +++++++++++++++++++ docs/apps.md | 127 +++++ src/Package/Apps.php | 335 ++++++++++++ src/Package/Apps/Installations.php | 153 ++++++ src/Package/Apps/Marketplace.php | 213 ++++++++ src/Package/Apps/OauthApplications.php | 119 ++++ src/Package/Apps/Webhooks.php | 139 +++++ 11 files changed, 2619 insertions(+) create mode 100644 Tests/Package/Apps/InstallationsTest.php create mode 100644 Tests/Package/Apps/MarketplaceTest.php create mode 100644 Tests/Package/Apps/OauthApplicationsTest.php create mode 100644 Tests/Package/Apps/WebhooksTest.php create mode 100644 Tests/Package/AppsTest.php create mode 100644 docs/apps.md create mode 100644 src/Package/Apps.php create mode 100644 src/Package/Apps/Installations.php create mode 100644 src/Package/Apps/Marketplace.php create mode 100644 src/Package/Apps/OauthApplications.php create mode 100644 src/Package/Apps/Webhooks.php diff --git a/Tests/Package/Apps/InstallationsTest.php b/Tests/Package/Apps/InstallationsTest.php new file mode 100644 index 00000000..64d36ee1 --- /dev/null +++ b/Tests/Package/Apps/InstallationsTest.php @@ -0,0 +1,250 @@ +object = new Installations($this->options, $this->client); + } + + /** + * Tests the getListRepositories method. + * + * @return void + */ + public function testGetListRepositories() + { + $this->client->expects($this->once()) + ->method('get') + ->with('/installation/repositories?page=2&per_page=10', [], 0) + ->willReturn($this->response); + + $this->assertEquals( + json_decode($this->sampleString), + $this->object->getListRepositories(2, 10) + ); + } + + /** + * Tests the getListRepositories method - failure. + * + * @return void + */ + public function testGetListRepositoriesFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->response = $this->getResponseObject($this->errorString, 500); + + $this->client->expects($this->once()) + ->method('get') + ->willReturn($this->response); + + $this->object->getListRepositories(2, 10); + } + + /** + * Tests the revokeAccessToken method. + * + * @return void + */ + public function testRevokeAccessToken() + { + $this->response = $this->getResponseObject('', 204); + $this->client->expects($this->once()) + ->method('delete') + ->with('/installation/token', [], 0) + ->willReturn($this->response); + + $this->assertNull($this->object->revokeAccessToken()); + } + + /** + * Tests the revokeAccessToken method - failure. + * + * @return void + */ + public function testRevokeAccessTokenFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->response = $this->getResponseObject($this->errorString, 500); + + $this->client->expects($this->once()) + ->method('delete') + ->willReturn($this->response); + + $this->object->revokeAccessToken(); + } + + /** + * Tests the getListForAuthenticatedUser method. + * + * @return void + */ + public function testGetListForAuthenticatedUser() + { + $this->client->expects($this->once()) + ->method('get') + ->with('/user/installations?page=2&per_page=10', [], 0) + ->willReturn($this->response); + + $this->assertEquals( + json_decode($this->sampleString), + $this->object->getListForAuthenticatedUser(2, 10) + ); + } + + /** + * Tests the getListForAuthenticatedUser method - failure. + * + * @return void + */ + public function testGetListForAuthenticatedUserFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->response = $this->getResponseObject($this->errorString, 500); + + $this->client->expects($this->once()) + ->method('get') + ->willReturn($this->response); + + $this->object->getListForAuthenticatedUser(2, 10); + } + + /** + * Tests the getListRepositoriesForAuthenticatedUser method. + * + * @return void + */ + public function testGetListRepositoriesForAuthenticatedUser() + { + $this->client->expects($this->once()) + ->method('get') + ->with('/user/installations/7/repositories?page=2&per_page=10', [], 0) + ->willReturn($this->response); + + $this->assertEquals( + json_decode($this->sampleString), + $this->object->getListRepositoriesForAuthenticatedUser(7, 2, 10) + ); + } + + /** + * Tests the getListRepositoriesForAuthenticatedUser method - failure. + * + * @return void + */ + public function testGetListRepositoriesForAuthenticatedUserFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->response = $this->getResponseObject($this->errorString, 500); + + $this->client->expects($this->once()) + ->method('get') + ->willReturn($this->response); + + $this->object->getListRepositoriesForAuthenticatedUser(7, 2, 10); + } + + /** + * Tests the addRepository method. + * + * @return void + */ + public function testAddRepository() + { + $this->response = $this->getResponseObject('', 204); + $this->client->expects($this->once()) + ->method('put') + ->with('/user/installations/7/repositories/9', '', [], 0) + ->willReturn($this->response); + + $this->assertNull($this->object->addRepository(7, 9)); + } + + /** + * Tests the addRepository method - failure. + * + * @return void + */ + public function testAddRepositoryFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->response = $this->getResponseObject($this->errorString, 500); + + $this->client->expects($this->once()) + ->method('put') + ->willReturn($this->response); + + $this->object->addRepository(7, 9); + } + + /** + * Tests the removeRepository method. + * + * @return void + */ + public function testRemoveRepository() + { + $this->response = $this->getResponseObject('', 204); + $this->client->expects($this->once()) + ->method('delete') + ->with('/user/installations/7/repositories/9', [], 0) + ->willReturn($this->response); + + $this->assertNull($this->object->removeRepository(7, 9)); + } + + /** + * Tests the removeRepository method - failure. + * + * @return void + */ + public function testRemoveRepositoryFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->response = $this->getResponseObject($this->errorString, 500); + + $this->client->expects($this->once()) + ->method('delete') + ->willReturn($this->response); + + $this->object->removeRepository(7, 9); + } +} diff --git a/Tests/Package/Apps/MarketplaceTest.php b/Tests/Package/Apps/MarketplaceTest.php new file mode 100644 index 00000000..0725bc34 --- /dev/null +++ b/Tests/Package/Apps/MarketplaceTest.php @@ -0,0 +1,328 @@ +object = new Marketplace($this->options, $this->client); + } + + /** + * Tests the getSubscriptionPlanForAccount method. + * + * @return void + */ + public function testGetSubscriptionPlanForAccount() + { + $this->client->expects($this->once()) + ->method('get') + ->with('/marketplace_listing/accounts/3', [], 0) + ->willReturn($this->response); + + $this->assertEquals( + json_decode($this->sampleString), + $this->object->getSubscriptionPlanForAccount(3) + ); + } + + /** + * Tests the getSubscriptionPlanForAccount method - failure. + * + * @return void + */ + public function testGetSubscriptionPlanForAccountFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->response = $this->getResponseObject($this->errorString, 500); + + $this->client->expects($this->once()) + ->method('get') + ->willReturn($this->response); + + $this->object->getSubscriptionPlanForAccount(3); + } + + /** + * Tests the getListPlans method. + * + * @return void + */ + public function testGetListPlans() + { + $this->client->expects($this->once()) + ->method('get') + ->with('/marketplace_listing/plans?page=2&per_page=10', [], 0) + ->willReturn($this->response); + + $this->assertEquals( + json_decode($this->sampleString), + $this->object->getListPlans(2, 10) + ); + } + + /** + * Tests the getListPlans method - failure. + * + * @return void + */ + public function testGetListPlansFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->response = $this->getResponseObject($this->errorString, 500); + + $this->client->expects($this->once()) + ->method('get') + ->willReturn($this->response); + + $this->object->getListPlans(2, 10); + } + + /** + * Tests the getListAccountsForPlan method. + * + * @return void + */ + public function testGetListAccountsForPlan() + { + $this->client->expects($this->once()) + ->method('get') + ->with('/marketplace_listing/plans/2/accounts?page=2&per_page=10&sort=updated&direction=asc', [], 0) + ->willReturn($this->response); + + $this->assertEquals( + json_decode($this->sampleString), + $this->object->getListAccountsForPlan(2, ['sort' => 'updated', 'direction' => 'asc'], 2, 10) + ); + } + + /** + * Tests the getListAccountsForPlan method - failure. + * + * @return void + */ + public function testGetListAccountsForPlanFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->response = $this->getResponseObject($this->errorString, 500); + + $this->client->expects($this->once()) + ->method('get') + ->willReturn($this->response); + + $this->object->getListAccountsForPlan(2, ['sort' => 'updated', 'direction' => 'asc'], 2, 10); + } + + /** + * Tests the getSubscriptionPlanForAccountStubbed method. + * + * @return void + */ + public function testGetSubscriptionPlanForAccountStubbed() + { + $this->client->expects($this->once()) + ->method('get') + ->with('/marketplace_listing/stubbed/accounts/3', [], 0) + ->willReturn($this->response); + + $this->assertEquals( + json_decode($this->sampleString), + $this->object->getSubscriptionPlanForAccountStubbed(3) + ); + } + + /** + * Tests the getSubscriptionPlanForAccountStubbed method - failure. + * + * @return void + */ + public function testGetSubscriptionPlanForAccountStubbedFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->response = $this->getResponseObject($this->errorString, 500); + + $this->client->expects($this->once()) + ->method('get') + ->willReturn($this->response); + + $this->object->getSubscriptionPlanForAccountStubbed(3); + } + + /** + * Tests the getListPlansStubbed method. + * + * @return void + */ + public function testGetListPlansStubbed() + { + $this->client->expects($this->once()) + ->method('get') + ->with('/marketplace_listing/stubbed/plans?page=2&per_page=10', [], 0) + ->willReturn($this->response); + + $this->assertEquals( + json_decode($this->sampleString), + $this->object->getListPlansStubbed(2, 10) + ); + } + + /** + * Tests the getListPlansStubbed method - failure. + * + * @return void + */ + public function testGetListPlansStubbedFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->response = $this->getResponseObject($this->errorString, 500); + + $this->client->expects($this->once()) + ->method('get') + ->willReturn($this->response); + + $this->object->getListPlansStubbed(2, 10); + } + + /** + * Tests the getListAccountsForPlanStubbed method. + * + * @return void + */ + public function testGetListAccountsForPlanStubbed() + { + $this->client->expects($this->once()) + ->method('get') + ->with('/marketplace_listing/stubbed/plans/2/accounts?page=2&per_page=10&sort=created', [], 0) + ->willReturn($this->response); + + $this->assertEquals( + json_decode($this->sampleString), + $this->object->getListAccountsForPlanStubbed(2, ['sort' => 'created'], 2, 10) + ); + } + + /** + * Tests the getListAccountsForPlanStubbed method - failure. + * + * @return void + */ + public function testGetListAccountsForPlanStubbedFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->response = $this->getResponseObject($this->errorString, 500); + + $this->client->expects($this->once()) + ->method('get') + ->willReturn($this->response); + + $this->object->getListAccountsForPlanStubbed(2, ['sort' => 'created'], 2, 10); + } + + /** + * Tests the getListSubscriptionsForAuthenticatedUser method. + * + * @return void + */ + public function testGetListSubscriptionsForAuthenticatedUser() + { + $this->client->expects($this->once()) + ->method('get') + ->with('/user/marketplace_purchases?page=2&per_page=10', [], 0) + ->willReturn($this->response); + + $this->assertEquals( + json_decode($this->sampleString), + $this->object->getListSubscriptionsForAuthenticatedUser(2, 10) + ); + } + + /** + * Tests the getListSubscriptionsForAuthenticatedUser method - failure. + * + * @return void + */ + public function testGetListSubscriptionsForAuthenticatedUserFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->response = $this->getResponseObject($this->errorString, 500); + + $this->client->expects($this->once()) + ->method('get') + ->willReturn($this->response); + + $this->object->getListSubscriptionsForAuthenticatedUser(2, 10); + } + + /** + * Tests the getListSubscriptionsForAuthenticatedUserStubbed method. + * + * @return void + */ + public function testGetListSubscriptionsForAuthenticatedUserStubbed() + { + $this->client->expects($this->once()) + ->method('get') + ->with('/user/marketplace_purchases/stubbed?page=2&per_page=10', [], 0) + ->willReturn($this->response); + + $this->assertEquals( + json_decode($this->sampleString), + $this->object->getListSubscriptionsForAuthenticatedUserStubbed(2, 10) + ); + } + + /** + * Tests the getListSubscriptionsForAuthenticatedUserStubbed method - failure. + * + * @return void + */ + public function testGetListSubscriptionsForAuthenticatedUserStubbedFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->response = $this->getResponseObject($this->errorString, 500); + + $this->client->expects($this->once()) + ->method('get') + ->willReturn($this->response); + + $this->object->getListSubscriptionsForAuthenticatedUserStubbed(2, 10); + } +} diff --git a/Tests/Package/Apps/OauthApplicationsTest.php b/Tests/Package/Apps/OauthApplicationsTest.php new file mode 100644 index 00000000..946da1aa --- /dev/null +++ b/Tests/Package/Apps/OauthApplicationsTest.php @@ -0,0 +1,188 @@ +object = new OauthApplications($this->options, $this->client); + } + + /** + * Tests the deleteAuthorization method. + * + * @return void + */ + public function testDeleteAuthorization() + { + $this->response = $this->getResponseObject('', 204); + $body = '{"access_token":"e72e16c7e42f292c6912e7710c838347ae178b4a"}'; + + $this->client->expects($this->once()) + ->method('delete') + ->with('/applications/Iv1.8a61f9b3a7aba766/grant', [], 0, $body) + ->willReturn($this->response); + + $this->assertNull($this->object->deleteAuthorization('Iv1.8a61f9b3a7aba766', 'e72e16c7e42f292c6912e7710c838347ae178b4a')); + } + + /** + * Tests the deleteAuthorization method - failure. + * + * @return void + */ + public function testDeleteAuthorizationFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->response = $this->getResponseObject($this->errorString, 500); + + $this->client->expects($this->once()) + ->method('delete') + ->willReturn($this->response); + + $this->object->deleteAuthorization('Iv1.8a61f9b3a7aba766', 'e72e16c7e42f292c6912e7710c838347ae178b4a'); + } + + /** + * Tests the checkToken method. + * + * @return void + */ + public function testCheckToken() + { + $body = '{"access_token":"e72e16c7e42f292c6912e7710c838347ae178b4a"}'; + + $this->client->expects($this->once()) + ->method('post') + ->with('/applications/Iv1.8a61f9b3a7aba766/token', $body, [], 0) + ->willReturn($this->response); + + $this->assertEquals( + json_decode($this->sampleString), + $this->object->checkToken('Iv1.8a61f9b3a7aba766', 'e72e16c7e42f292c6912e7710c838347ae178b4a') + ); + } + + /** + * Tests the checkToken method - failure. + * + * @return void + */ + public function testCheckTokenFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->response = $this->getResponseObject($this->errorString, 500); + + $this->client->expects($this->once()) + ->method('post') + ->willReturn($this->response); + + $this->object->checkToken('Iv1.8a61f9b3a7aba766', 'e72e16c7e42f292c6912e7710c838347ae178b4a'); + } + + /** + * Tests the resetToken method. + * + * @return void + */ + public function testResetToken() + { + $body = '{"access_token":"e72e16c7e42f292c6912e7710c838347ae178b4a"}'; + + $this->client->expects($this->once()) + ->method('patch') + ->with('/applications/Iv1.8a61f9b3a7aba766/token', $body, [], 0) + ->willReturn($this->response); + + $this->assertEquals( + json_decode($this->sampleString), + $this->object->resetToken('Iv1.8a61f9b3a7aba766', 'e72e16c7e42f292c6912e7710c838347ae178b4a') + ); + } + + /** + * Tests the resetToken method - failure. + * + * @return void + */ + public function testResetTokenFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->response = $this->getResponseObject($this->errorString, 500); + + $this->client->expects($this->once()) + ->method('patch') + ->willReturn($this->response); + + $this->object->resetToken('Iv1.8a61f9b3a7aba766', 'e72e16c7e42f292c6912e7710c838347ae178b4a'); + } + + /** + * Tests the deleteToken method. + * + * @return void + */ + public function testDeleteToken() + { + $this->response = $this->getResponseObject('', 204); + $body = '{"access_token":"e72e16c7e42f292c6912e7710c838347ae178b4a"}'; + + $this->client->expects($this->once()) + ->method('delete') + ->with('/applications/Iv1.8a61f9b3a7aba766/token', [], 0, $body) + ->willReturn($this->response); + + $this->assertNull($this->object->deleteToken('Iv1.8a61f9b3a7aba766', 'e72e16c7e42f292c6912e7710c838347ae178b4a')); + } + + /** + * Tests the deleteToken method - failure. + * + * @return void + */ + public function testDeleteTokenFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->response = $this->getResponseObject($this->errorString, 500); + + $this->client->expects($this->once()) + ->method('delete') + ->willReturn($this->response); + + $this->object->deleteToken('Iv1.8a61f9b3a7aba766', 'e72e16c7e42f292c6912e7710c838347ae178b4a'); + } +} diff --git a/Tests/Package/Apps/WebhooksTest.php b/Tests/Package/Apps/WebhooksTest.php new file mode 100644 index 00000000..1ed73c68 --- /dev/null +++ b/Tests/Package/Apps/WebhooksTest.php @@ -0,0 +1,223 @@ +object = new Webhooks($this->options, $this->client); + } + + /** + * Tests the getConfig method. + * + * @return void + */ + public function testGetConfig() + { + $this->client->expects($this->once()) + ->method('get') + ->with('/app/hook/config', [], 0) + ->willReturn($this->response); + + $this->assertEquals( + json_decode($this->sampleString), + $this->object->getConfig() + ); + } + + /** + * Tests the getConfig method - failure. + * + * @return void + */ + public function testGetConfigFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->response = $this->getResponseObject($this->errorString, 500); + + $this->client->expects($this->once()) + ->method('get') + ->willReturn($this->response); + + $this->object->getConfig(); + } + + /** + * Tests the editConfig method. + * + * @return void + */ + public function testEditConfig() + { + $body = '{"content_type":"json","insecure_ssl":"0"}'; + + $this->client->expects($this->once()) + ->method('patch') + ->with('/app/hook/config', $body, [], 0) + ->willReturn($this->response); + + $this->assertEquals( + json_decode($this->sampleString), + $this->object->editConfig(['content_type' => 'json', 'insecure_ssl' => '0']) + ); + } + + /** + * Tests the editConfig method - failure. + * + * @return void + */ + public function testEditConfigFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->response = $this->getResponseObject($this->errorString, 500); + + $this->client->expects($this->once()) + ->method('patch') + ->willReturn($this->response); + + $this->object->editConfig(['content_type' => 'json', 'insecure_ssl' => '0']); + } + + /** + * Tests the getListDeliveries method. + * + * @return void + */ + public function testGetListDeliveries() + { + $this->client->expects($this->once()) + ->method('get') + ->with('/app/hook/deliveries?page=2&per_page=10&cursor=v1_12077215967&status=failure', [], 0) + ->willReturn($this->response); + + $this->assertEquals( + json_decode($this->sampleString), + $this->object->getListDeliveries(['cursor' => 'v1_12077215967', 'status' => 'failure'], 2, 10) + ); + } + + /** + * Tests the getListDeliveries method - failure. + * + * @return void + */ + public function testGetListDeliveriesFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->response = $this->getResponseObject($this->errorString, 500); + + $this->client->expects($this->once()) + ->method('get') + ->willReturn($this->response); + + $this->object->getListDeliveries(['cursor' => 'v1_12077215967', 'status' => 'failure'], 2, 10); + } + + /** + * Tests the getDelivery method. + * + * @return void + */ + public function testGetDelivery() + { + $this->client->expects($this->once()) + ->method('get') + ->with('/app/hook/deliveries/12', [], 0) + ->willReturn($this->response); + + $this->assertEquals( + json_decode($this->sampleString), + $this->object->getDelivery(12) + ); + } + + /** + * Tests the getDelivery method - failure. + * + * @return void + */ + public function testGetDeliveryFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->response = $this->getResponseObject($this->errorString, 500); + + $this->client->expects($this->once()) + ->method('get') + ->willReturn($this->response); + + $this->object->getDelivery(12); + } + + /** + * Tests the redeliver method. + * + * @return void + */ + public function testRedeliver() + { + $this->response = $this->getResponseObject($this->sampleString, 202); + $this->client->expects($this->once()) + ->method('post') + ->with('/app/hook/deliveries/12/attempts', '', [], 0) + ->willReturn($this->response); + + $this->assertEquals( + json_decode($this->sampleString), + $this->object->redeliver(12) + ); + } + + /** + * Tests the redeliver method - failure. + * + * @return void + */ + public function testRedeliverFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->response = $this->getResponseObject($this->errorString, 500); + + $this->client->expects($this->once()) + ->method('post') + ->willReturn($this->response); + + $this->object->redeliver(12); + } +} diff --git a/Tests/Package/AppsTest.php b/Tests/Package/AppsTest.php new file mode 100644 index 00000000..c5dd9cea --- /dev/null +++ b/Tests/Package/AppsTest.php @@ -0,0 +1,544 @@ +object = new Apps($this->options, $this->client); + } + + /** + * Tests the getAuthenticated method. + * + * @return void + */ + public function testGetAuthenticated() + { + $this->client->expects($this->once()) + ->method('get') + ->with('/app', [], 0) + ->willReturn($this->response); + + $this->assertEquals( + json_decode($this->sampleString), + $this->object->getAuthenticated() + ); + } + + /** + * Tests the getAuthenticated method - failure. + * + * @return void + */ + public function testGetAuthenticatedFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->response = $this->getResponseObject($this->errorString, 500); + + $this->client->expects($this->once()) + ->method('get') + ->willReturn($this->response); + + $this->object->getAuthenticated(); + } + + /** + * Tests the createFromManifest method. + * + * @return void + */ + public function testCreateFromManifest() + { + $this->response = $this->getResponseObject($this->sampleString, 201); + $this->client->expects($this->once()) + ->method('post') + ->with('/app-manifests/abc123/conversions', '', [], 0) + ->willReturn($this->response); + + $this->assertEquals( + json_decode($this->sampleString), + $this->object->createFromManifest('abc123') + ); + } + + /** + * Tests the createFromManifest method - failure. + * + * @return void + */ + public function testCreateFromManifestFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->response = $this->getResponseObject($this->errorString, 500); + + $this->client->expects($this->once()) + ->method('post') + ->willReturn($this->response); + + $this->object->createFromManifest('abc123'); + } + + /** + * Tests the getListInstallationRequests method. + * + * @return void + */ + public function testGetListInstallationRequests() + { + $this->client->expects($this->once()) + ->method('get') + ->with('/app/installation-requests?page=2&per_page=10', [], 0) + ->willReturn($this->response); + + $this->assertEquals( + json_decode($this->sampleString), + $this->object->getListInstallationRequests(2, 10) + ); + } + + /** + * Tests the getListInstallationRequests method - failure. + * + * @return void + */ + public function testGetListInstallationRequestsFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->response = $this->getResponseObject($this->errorString, 500); + + $this->client->expects($this->once()) + ->method('get') + ->willReturn($this->response); + + $this->object->getListInstallationRequests(2, 10); + } + + /** + * Tests the getListInstallations method. + * + * @return void + */ + public function testGetListInstallations() + { + $this->client->expects($this->once()) + ->method('get') + ->with('/app/installations?page=2&per_page=10&since=2026-01-01T00:00:00Z', [], 0) + ->willReturn($this->response); + + $this->assertEquals( + json_decode($this->sampleString), + $this->object->getListInstallations(['since' => '2026-01-01T00:00:00Z'], 2, 10) + ); + } + + /** + * Tests the getListInstallations method - failure. + * + * @return void + */ + public function testGetListInstallationsFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->response = $this->getResponseObject($this->errorString, 500); + + $this->client->expects($this->once()) + ->method('get') + ->willReturn($this->response); + + $this->object->getListInstallations(['since' => '2026-01-01T00:00:00Z'], 2, 10); + } + + /** + * Tests the getInstallation method. + * + * @return void + */ + public function testGetInstallation() + { + $this->client->expects($this->once()) + ->method('get') + ->with('/app/installations/7', [], 0) + ->willReturn($this->response); + + $this->assertEquals( + json_decode($this->sampleString), + $this->object->getInstallation(7) + ); + } + + /** + * Tests the getInstallation method - failure. + * + * @return void + */ + public function testGetInstallationFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->response = $this->getResponseObject($this->errorString, 500); + + $this->client->expects($this->once()) + ->method('get') + ->willReturn($this->response); + + $this->object->getInstallation(7); + } + + /** + * Tests the deleteInstallation method. + * + * @return void + */ + public function testDeleteInstallation() + { + $this->response = $this->getResponseObject('', 204); + $this->client->expects($this->once()) + ->method('delete') + ->with('/app/installations/7', [], 0) + ->willReturn($this->response); + + $this->assertNull($this->object->deleteInstallation(7)); + } + + /** + * Tests the deleteInstallation method - failure. + * + * @return void + */ + public function testDeleteInstallationFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->response = $this->getResponseObject($this->errorString, 500); + + $this->client->expects($this->once()) + ->method('delete') + ->willReturn($this->response); + + $this->object->deleteInstallation(7); + } + + /** + * Tests the createInstallationAccessToken method. + * + * @return void + */ + public function testCreateInstallationAccessToken() + { + $this->response = $this->getResponseObject($this->sampleString, 201); + $body = '{"repository_ids":[1296269]}'; + + $this->client->expects($this->once()) + ->method('post') + ->with('/app/installations/7/access_tokens', $body, [], 0) + ->willReturn($this->response); + + $this->assertEquals( + json_decode($this->sampleString), + $this->object->createInstallationAccessToken(7, ['repository_ids' => [1296269]]) + ); + } + + /** + * Tests the createInstallationAccessToken method - failure. + * + * @return void + */ + public function testCreateInstallationAccessTokenFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->response = $this->getResponseObject($this->errorString, 500); + + $this->client->expects($this->once()) + ->method('post') + ->willReturn($this->response); + + $this->object->createInstallationAccessToken(7, ['repository_ids' => [1296269]]); + } + + /** + * Tests the suspendInstallation method. + * + * @return void + */ + public function testSuspendInstallation() + { + $this->response = $this->getResponseObject('', 204); + $this->client->expects($this->once()) + ->method('put') + ->with('/app/installations/7/suspended', '', [], 0) + ->willReturn($this->response); + + $this->assertNull($this->object->suspendInstallation(7)); + } + + /** + * Tests the suspendInstallation method - failure. + * + * @return void + */ + public function testSuspendInstallationFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->response = $this->getResponseObject($this->errorString, 500); + + $this->client->expects($this->once()) + ->method('put') + ->willReturn($this->response); + + $this->object->suspendInstallation(7); + } + + /** + * Tests the unsuspendInstallation method. + * + * @return void + */ + public function testUnsuspendInstallation() + { + $this->response = $this->getResponseObject('', 204); + $this->client->expects($this->once()) + ->method('delete') + ->with('/app/installations/7/suspended', [], 0) + ->willReturn($this->response); + + $this->assertNull($this->object->unsuspendInstallation(7)); + } + + /** + * Tests the unsuspendInstallation method - failure. + * + * @return void + */ + public function testUnsuspendInstallationFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->response = $this->getResponseObject($this->errorString, 500); + + $this->client->expects($this->once()) + ->method('delete') + ->willReturn($this->response); + + $this->object->unsuspendInstallation(7); + } + + /** + * Tests the scopeToken method. + * + * @return void + */ + public function testScopeToken() + { + $body = '{"target":"octocat","access_token":"e72e16c7e42f292c6912e7710c838347ae178b4a"}'; + + $this->client->expects($this->once()) + ->method('post') + ->with('/applications/Iv1.8a61f9b3a7aba766/token/scoped', $body, [], 0) + ->willReturn($this->response); + + $this->assertEquals( + json_decode($this->sampleString), + $this->object->scopeToken('Iv1.8a61f9b3a7aba766', 'e72e16c7e42f292c6912e7710c838347ae178b4a', ['target' => 'octocat']) + ); + } + + /** + * Tests the scopeToken method - failure. + * + * @return void + */ + public function testScopeTokenFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->response = $this->getResponseObject($this->errorString, 500); + + $this->client->expects($this->once()) + ->method('post') + ->willReturn($this->response); + + $this->object->scopeToken('Iv1.8a61f9b3a7aba766', 'e72e16c7e42f292c6912e7710c838347ae178b4a', ['target' => 'octocat']); + } + + /** + * Tests the getBySlug method. + * + * @return void + */ + public function testGetBySlug() + { + $this->client->expects($this->once()) + ->method('get') + ->with('/apps/octoapp', [], 0) + ->willReturn($this->response); + + $this->assertEquals( + json_decode($this->sampleString), + $this->object->getBySlug('octoapp') + ); + } + + /** + * Tests the getBySlug method - failure. + * + * @return void + */ + public function testGetBySlugFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->response = $this->getResponseObject($this->errorString, 500); + + $this->client->expects($this->once()) + ->method('get') + ->willReturn($this->response); + + $this->object->getBySlug('octoapp'); + } + + /** + * Tests the getInstallationForOrg method. + * + * @return void + */ + public function testGetInstallationForOrg() + { + $this->client->expects($this->once()) + ->method('get') + ->with('/orgs/joomla/installation', [], 0) + ->willReturn($this->response); + + $this->assertEquals( + json_decode($this->sampleString), + $this->object->getInstallationForOrg('joomla') + ); + } + + /** + * Tests the getInstallationForOrg method - failure. + * + * @return void + */ + public function testGetInstallationForOrgFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->response = $this->getResponseObject($this->errorString, 500); + + $this->client->expects($this->once()) + ->method('get') + ->willReturn($this->response); + + $this->object->getInstallationForOrg('joomla'); + } + + /** + * Tests the getInstallationForRepo method. + * + * @return void + */ + public function testGetInstallationForRepo() + { + $this->client->expects($this->once()) + ->method('get') + ->with('/repos/joomla/joomla-platform/installation', [], 0) + ->willReturn($this->response); + + $this->assertEquals( + json_decode($this->sampleString), + $this->object->getInstallationForRepo('joomla', 'joomla-platform') + ); + } + + /** + * Tests the getInstallationForRepo method - failure. + * + * @return void + */ + public function testGetInstallationForRepoFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->response = $this->getResponseObject($this->errorString, 500); + + $this->client->expects($this->once()) + ->method('get') + ->willReturn($this->response); + + $this->object->getInstallationForRepo('joomla', 'joomla-platform'); + } + + /** + * Tests the getInstallationForUser method. + * + * @return void + */ + public function testGetInstallationForUser() + { + $this->client->expects($this->once()) + ->method('get') + ->with('/users/octocat/installation', [], 0) + ->willReturn($this->response); + + $this->assertEquals( + json_decode($this->sampleString), + $this->object->getInstallationForUser('octocat') + ); + } + + /** + * Tests the getInstallationForUser method - failure. + * + * @return void + */ + public function testGetInstallationForUserFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->response = $this->getResponseObject($this->errorString, 500); + + $this->client->expects($this->once()) + ->method('get') + ->willReturn($this->response); + + $this->object->getInstallationForUser('octocat'); + } +} diff --git a/docs/apps.md b/docs/apps.md new file mode 100644 index 00000000..c0f3bcbd --- /dev/null +++ b/docs/apps.md @@ -0,0 +1,127 @@ +# Apps + +The Apps package covers the [GitHub Apps API](https://docs.github.com/rest/apps): the authenticated app and its +installations, installation access tokens, app installations visible to a user, GitHub Marketplace listings, +OAuth application tokens and the app webhook. It is reached as `$github->apps`; the operations of the `apps` +section live on that class, the others in the sub-packages `$github->apps->installations`, +`$github->apps->marketplace`, `$github->apps->oauthApplications` and `$github->apps->webhooks`, for example +`$github->apps->installations->getListRepositories()`. + +## Authentication + +Most of these endpoints do not accept a normal user token. The library itself only knows two ways to +authenticate: `gh.token` (sent as `Authorization: token `) and `api.username` / `api.password` +(HTTP Basic auth, used only when `gh.token` is not set). The credentials each operation needs are noted in the +method docblocks and summarised here. + +| Credential | Operations | How to provide it | +| --- | --- | --- | +| JSON Web Token (JWT) of the app | `Apps`: getAuthenticated, getListInstallationRequests, getListInstallations, getInstallation, deleteInstallation, createInstallationAccessToken, suspendInstallation, unsuspendInstallation, getInstallationForOrg, getInstallationForRepo, getInstallationForUser; all of `Webhooks`; the `/marketplace_listing/*` methods of `Marketplace` | An `Authorization: Bearer ` header set on the HTTP client (see below). **Passing the JWT as `gh.token` does not work**: GitHub accepts the `token` scheme for ordinary tokens, but [for a JWT it requires `Bearer`](https://docs.github.com/rest/authentication/authenticating-to-the-rest-api). | +| Client ID and client secret (Basic auth) | `Apps`: scopeToken; all of `OauthApplications` | Set `api.username` to the client ID and `api.password` to the client secret, and do not set `gh.token`. | +| Installation access token | `Installations`: getListRepositories, revokeAccessToken | `gh.token` (GitHub accepts it with the `token` scheme). Create the token with `createInstallationAccessToken()`. | +| User access token / personal access token | `Installations`: getListForAuthenticatedUser, getListRepositoriesForAuthenticatedUser, addRepository, removeRepository; `Marketplace`: getListSubscriptionsForAuthenticatedUser(Stubbed) | `gh.token`. | +| None | `Apps`: getBySlug (public apps), createFromManifest (the temporary code is the credential) | — | + +The JWT has to be signed by the caller with the app's private key (RS256, `iss` = client ID or app ID, at most +10 minutes valid); the library does not create it. Because the library never overwrites an `Authorization` +header that is already configured on the HTTP client, a Bearer header can be set through the `headers` option. +Use a separate `Github` object for the JWT calls, since the header then applies to every request of that client: + +```php +use Joomla\Github\Github; +use Joomla\Registry\Registry; + +// Authenticate as the app (JWT) to create an installation access token +$appOptions = new Registry(); +$appOptions->set('headers', ['Authorization' => 'Bearer ' . $jwt]); + +$app = new Github($appOptions); +$token = $app->apps->createInstallationAccessToken($installationId, ['repositories' => ['joomla-cms']]); + +// Use the installation access token as a normal token +$options = new Registry(); +$options->set('gh.token', $token->token); + +$github = new Github($options); +$repos = $github->apps->installations->getListRepositories(); + +// OAuth app endpoints use Basic auth with the client ID and secret +$oauthOptions = new Registry(); +$oauthOptions->set('api.username', $clientId); +$oauthOptions->set('api.password', $clientSecret); + +$check = (new Github($oauthOptions))->apps->oauthApplications->checkToken($clientId, $userToken); +``` + +When you pass your own `Joomla\Http\Http` client to `Github`, set the header on that client instead +(`new Http(['headers' => ['Authorization' => 'Bearer ' . $jwt]])`). + +Optional request body fields are passed in `$options` and optional query parameters in `$filters`; the +docblock of each method lists the accepted keys. `Webhooks::getListDeliveries()` uses cursor-based pagination: +pass the `cursor` filter taken from the `Link` response header; only `$limit` (`per_page`) is used by GitHub. + +## Apps (`$github->apps`) + +| Method | Endpoint | +| --- | --- | +| getAuthenticated() | GET /app | +| createFromManifest($code) | POST /app-manifests/{code}/conversions | +| getListInstallationRequests($page, $limit) | GET /app/installation-requests | +| getListInstallations($filters, $page, $limit) | GET /app/installations | +| getInstallation($installationId) | GET /app/installations/{installation_id} | +| deleteInstallation($installationId) | DELETE /app/installations/{installation_id} | +| createInstallationAccessToken($installationId, $options) | POST /app/installations/{installation_id}/access_tokens | +| suspendInstallation($installationId) | PUT /app/installations/{installation_id}/suspended | +| unsuspendInstallation($installationId) | DELETE /app/installations/{installation_id}/suspended | +| scopeToken($clientId, $accessToken, $options) | POST /applications/{client_id}/token/scoped | +| getBySlug($appSlug) | GET /apps/{app_slug} | +| getInstallationForOrg($org) | GET /orgs/{org}/installation | +| getInstallationForRepo($owner, $repo) | GET /repos/{owner}/{repo}/installation | +| getInstallationForUser($username) | GET /users/{username}/installation | + +## Installations (`$github->apps->installations`) + +| Method | Endpoint | +| --- | --- | +| getListRepositories($page, $limit) | GET /installation/repositories | +| revokeAccessToken() | DELETE /installation/token | +| getListForAuthenticatedUser($page, $limit) | GET /user/installations | +| getListRepositoriesForAuthenticatedUser($installationId, $page, $limit) | GET /user/installations/{installation_id}/repositories | +| addRepository($installationId, $repositoryId) | PUT /user/installations/{installation_id}/repositories/{repository_id} | +| removeRepository($installationId, $repositoryId) | DELETE /user/installations/{installation_id}/repositories/{repository_id} | + +## Marketplace (`$github->apps->marketplace`) + +| Method | Endpoint | +| --- | --- | +| getSubscriptionPlanForAccount($accountId) | GET /marketplace_listing/accounts/{account_id} | +| getListPlans($page, $limit) | GET /marketplace_listing/plans | +| getListAccountsForPlan($planId, $filters, $page, $limit) | GET /marketplace_listing/plans/{plan_id}/accounts | +| getSubscriptionPlanForAccountStubbed($accountId) | GET /marketplace_listing/stubbed/accounts/{account_id} | +| getListPlansStubbed($page, $limit) | GET /marketplace_listing/stubbed/plans | +| getListAccountsForPlanStubbed($planId, $filters, $page, $limit) | GET /marketplace_listing/stubbed/plans/{plan_id}/accounts | +| getListSubscriptionsForAuthenticatedUser($page, $limit) | GET /user/marketplace_purchases | +| getListSubscriptionsForAuthenticatedUserStubbed($page, $limit) | GET /user/marketplace_purchases/stubbed | + +The `*Stubbed` methods call the stubbed endpoints that return test data for apps that are not yet listed. + +## OAuth applications (`$github->apps->oauthApplications`) + +| Method | Endpoint | +| --- | --- | +| deleteAuthorization($clientId, $accessToken) | DELETE /applications/{client_id}/grant | +| checkToken($clientId, $accessToken) | POST /applications/{client_id}/token | +| resetToken($clientId, $accessToken) | PATCH /applications/{client_id}/token | +| deleteToken($clientId, $accessToken) | DELETE /applications/{client_id}/token | + +The delete operations send the access token in the request body of the `DELETE` request, as GitHub requires. + +## Webhooks (`$github->apps->webhooks`) + +| Method | Endpoint | +| --- | --- | +| getConfig() | GET /app/hook/config | +| editConfig($options) | PATCH /app/hook/config | +| getListDeliveries($filters, $page, $limit) | GET /app/hook/deliveries | +| getDelivery($deliveryId) | GET /app/hook/deliveries/{delivery_id} | +| redeliver($deliveryId) | POST /app/hook/deliveries/{delivery_id}/attempts | diff --git a/src/Package/Apps.php b/src/Package/Apps.php new file mode 100644 index 00000000..b3ea2c94 --- /dev/null +++ b/src/Package/Apps.php @@ -0,0 +1,335 @@ +processResponse($this->client->get($this->fetchUrl($path))); + } + + /** + * Create a GitHub App from a manifest. + * + * No authentication is needed; the temporary code is the credential. + * + * @param string $code The temporary code returned by the manifest flow. + * + * @return object + * + * @link https://docs.github.com/rest/apps/apps#create-a-github-app-from-a-manifest + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + public function createFromManifest(string $code) + { + // Build the request path. + $path = '/app-manifests/' . $code . '/conversions'; + + return $this->processResponse($this->client->post($this->fetchUrl($path), ''), 201); + } + + /** + * List installation requests for the authenticated app. + * + * Authenticate as the GitHub App with a JWT (see docs/apps.md). + * + * @param integer $page The page number from which to get items. + * @param integer $limit The number of items on a page. + * + * @return array + * + * @link https://docs.github.com/rest/apps/apps#list-installation-requests-for-the-authenticated-app + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + public function getListInstallationRequests(int $page = 0, int $limit = 0) + { + // Build the request path. + $path = '/app/installation-requests'; + + return $this->processResponse($this->client->get($this->fetchUrl($path, $page, $limit))); + } + + /** + * List installations for the authenticated app. + * + * Authenticate as the GitHub App with a JWT (see docs/apps.md). + * + * @param array $filters Optional query parameters: since, outdated. + * @param integer $page The page number from which to get items. + * @param integer $limit The number of items on a page. + * + * @return array + * + * @link https://docs.github.com/rest/apps/apps#list-installations-for-the-authenticated-app + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + public function getListInstallations(array $filters = [], int $page = 0, int $limit = 0) + { + // Build the request path. + $path = '/app/installations'; + + $uri = $this->fetchUrl($path, $page, $limit); + + foreach ($filters as $key => $value) { + $uri->setVar($key, $value); + } + + return $this->processResponse($this->client->get($uri)); + } + + /** + * Get an installation for the authenticated app. + * + * Authenticate as the GitHub App with a JWT (see docs/apps.md). + * + * @param integer $installationId Installation identifier. + * + * @return object + * + * @link https://docs.github.com/rest/apps/apps#get-an-installation-for-the-authenticated-app + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + public function getInstallation(int $installationId) + { + // Build the request path. + $path = '/app/installations/' . $installationId; + + return $this->processResponse($this->client->get($this->fetchUrl($path))); + } + + /** + * Delete an installation for the authenticated app. + * + * Authenticate as the GitHub App with a JWT (see docs/apps.md). + * + * @param integer $installationId Installation identifier. + * + * @return void + * + * @link https://docs.github.com/rest/apps/apps#delete-an-installation-for-the-authenticated-app + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + public function deleteInstallation(int $installationId) + { + // Build the request path. + $path = '/app/installations/' . $installationId; + + $this->processResponse($this->client->delete($this->fetchUrl($path)), 204); + } + + /** + * Create an installation access token for an app. + * + * Authenticate as the GitHub App with a JWT (see docs/apps.md). + * + * @param integer $installationId Installation identifier. + * @param array $options Optional request body fields: repositories, repository_ids, permissions. + * + * @return object + * + * @link https://docs.github.com/rest/apps/apps#create-an-installation-access-token-for-an-app + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + public function createInstallationAccessToken(int $installationId, array $options = []) + { + // Build the request path. + $path = '/app/installations/' . $installationId . '/access_tokens'; + + $data = json_encode((object) $options); + + return $this->processResponse($this->client->post($this->fetchUrl($path), $data), 201); + } + + /** + * Suspend an app installation. + * + * Authenticate as the GitHub App with a JWT (see docs/apps.md). + * + * @param integer $installationId Installation identifier. + * + * @return void + * + * @link https://docs.github.com/rest/apps/apps#suspend-an-app-installation + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + public function suspendInstallation(int $installationId) + { + // Build the request path. + $path = '/app/installations/' . $installationId . '/suspended'; + + $this->processResponse($this->client->put($this->fetchUrl($path), ''), 204); + } + + /** + * Unsuspend an app installation. + * + * Authenticate as the GitHub App with a JWT (see docs/apps.md). + * + * @param integer $installationId Installation identifier. + * + * @return void + * + * @link https://docs.github.com/rest/apps/apps#unsuspend-an-app-installation + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + public function unsuspendInstallation(int $installationId) + { + // Build the request path. + $path = '/app/installations/' . $installationId . '/suspended'; + + $this->processResponse($this->client->delete($this->fetchUrl($path)), 204); + } + + /** + * Create a scoped access token. + * + * Authenticate with Basic auth, the client ID as user name and the client secret as password (see docs/apps.md). + * + * @param string $clientId Client ID of the GitHub App or OAuth app. + * @param string $accessToken The OAuth access token. + * @param array $options Optional request body fields: target, target_id, repositories, repository_ids, permissions. + * + * @return object + * + * @link https://docs.github.com/rest/apps/apps#create-a-scoped-access-token + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + public function scopeToken(string $clientId, string $accessToken, array $options = []) + { + // Build the request path. + $path = '/applications/' . $clientId . '/token/scoped'; + + $data = json_encode(array_merge($options, ['access_token' => $accessToken])); + + return $this->processResponse($this->client->post($this->fetchUrl($path), $data)); + } + + /** + * Get an app. + * + * @param string $appSlug URL-friendly name of the GitHub App. + * + * @return object + * + * @link https://docs.github.com/rest/apps/apps#get-an-app + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + public function getBySlug(string $appSlug) + { + // Build the request path. + $path = '/apps/' . $appSlug; + + return $this->processResponse($this->client->get($this->fetchUrl($path))); + } + + /** + * Get an organization installation for the authenticated app. + * + * Authenticate as the GitHub App with a JWT (see docs/apps.md). + * + * @param string $org Organisation name. + * + * @return object + * + * @link https://docs.github.com/rest/apps/apps#get-an-organization-installation-for-the-authenticated-app + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + public function getInstallationForOrg(string $org) + { + // Build the request path. + $path = '/orgs/' . $org . '/installation'; + + return $this->processResponse($this->client->get($this->fetchUrl($path))); + } + + /** + * Get a repository installation for the authenticated app. + * + * Authenticate as the GitHub App with a JWT (see docs/apps.md). + * + * @param string $owner Repository owner. + * @param string $repo Repository name. + * + * @return object + * + * @link https://docs.github.com/rest/apps/apps#get-a-repository-installation-for-the-authenticated-app + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + public function getInstallationForRepo(string $owner, string $repo) + { + // Build the request path. + $path = '/repos/' . $owner . '/' . $repo . '/installation'; + + return $this->processResponse($this->client->get($this->fetchUrl($path))); + } + + /** + * Get a user installation for the authenticated app. + * + * Authenticate as the GitHub App with a JWT (see docs/apps.md). + * + * @param string $username GitHub user name. + * + * @return object + * + * @link https://docs.github.com/rest/apps/apps#get-a-user-installation-for-the-authenticated-app + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + public function getInstallationForUser(string $username) + { + // Build the request path. + $path = '/users/' . $username . '/installation'; + + return $this->processResponse($this->client->get($this->fetchUrl($path))); + } +} diff --git a/src/Package/Apps/Installations.php b/src/Package/Apps/Installations.php new file mode 100644 index 00000000..2ff040f8 --- /dev/null +++ b/src/Package/Apps/Installations.php @@ -0,0 +1,153 @@ +processResponse($this->client->get($this->fetchUrl($path, $page, $limit))); + } + + /** + * Revoke an installation access token. + * + * Revokes the installation access token used to authenticate the request. + * + * @return void + * + * @link https://docs.github.com/rest/apps/installations#revoke-an-installation-access-token + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + public function revokeAccessToken() + { + // Build the request path. + $path = '/installation/token'; + + $this->processResponse($this->client->delete($this->fetchUrl($path)), 204); + } + + /** + * List app installations accessible to the user access token. + * + * Authenticate with a user access token. + * + * @param integer $page The page number from which to get items. + * @param integer $limit The number of items on a page. + * + * @return object + * + * @link https://docs.github.com/rest/apps/installations#list-app-installations-accessible-to-the-user-access-token + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + public function getListForAuthenticatedUser(int $page = 0, int $limit = 0) + { + // Build the request path. + $path = '/user/installations'; + + return $this->processResponse($this->client->get($this->fetchUrl($path, $page, $limit))); + } + + /** + * List repositories accessible to the user access token. + * + * Authenticate with a user access token. + * + * @param integer $installationId Installation identifier. + * @param integer $page The page number from which to get items. + * @param integer $limit The number of items on a page. + * + * @return object + * + * @link https://docs.github.com/rest/apps/installations#list-repositories-accessible-to-the-user-access-token + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + public function getListRepositoriesForAuthenticatedUser(int $installationId, int $page = 0, int $limit = 0) + { + // Build the request path. + $path = '/user/installations/' . $installationId . '/repositories'; + + return $this->processResponse($this->client->get($this->fetchUrl($path, $page, $limit))); + } + + /** + * Add a repository to an app installation. + * + * Authenticate with a personal access token (classic) with the `repo` scope. + * + * @param integer $installationId Installation identifier. + * @param integer $repositoryId Repository identifier. + * + * @return void + * + * @link https://docs.github.com/rest/apps/installations#add-a-repository-to-an-app-installation + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + public function addRepository(int $installationId, int $repositoryId) + { + // Build the request path. + $path = '/user/installations/' . $installationId . '/repositories/' . $repositoryId; + + $this->processResponse($this->client->put($this->fetchUrl($path), ''), 204); + } + + /** + * Remove a repository from an app installation. + * + * Authenticate with a personal access token (classic) with the `repo` scope. + * + * @param integer $installationId Installation identifier. + * @param integer $repositoryId Repository identifier. + * + * @return void + * + * @link https://docs.github.com/rest/apps/installations#remove-a-repository-from-an-app-installation + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + public function removeRepository(int $installationId, int $repositoryId) + { + // Build the request path. + $path = '/user/installations/' . $installationId . '/repositories/' . $repositoryId; + + $this->processResponse($this->client->delete($this->fetchUrl($path)), 204); + } +} diff --git a/src/Package/Apps/Marketplace.php b/src/Package/Apps/Marketplace.php new file mode 100644 index 00000000..3fc04b6a --- /dev/null +++ b/src/Package/Apps/Marketplace.php @@ -0,0 +1,213 @@ +processResponse($this->client->get($this->fetchUrl($path))); + } + + /** + * List plans. + * + * Authenticate as the GitHub App with a JWT (see docs/apps.md). + * + * @param integer $page The page number from which to get items. + * @param integer $limit The number of items on a page. + * + * @return array + * + * @link https://docs.github.com/rest/apps/marketplace#list-plans + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + public function getListPlans(int $page = 0, int $limit = 0) + { + // Build the request path. + $path = '/marketplace_listing/plans'; + + return $this->processResponse($this->client->get($this->fetchUrl($path, $page, $limit))); + } + + /** + * List accounts for a plan. + * + * Authenticate as the GitHub App with a JWT (see docs/apps.md). + * + * @param integer $planId Plan identifier. + * @param array $filters Optional query parameters: sort, direction. + * @param integer $page The page number from which to get items. + * @param integer $limit The number of items on a page. + * + * @return array + * + * @link https://docs.github.com/rest/apps/marketplace#list-accounts-for-a-plan + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + public function getListAccountsForPlan(int $planId, array $filters = [], int $page = 0, int $limit = 0) + { + // Build the request path. + $path = '/marketplace_listing/plans/' . $planId . '/accounts'; + + $uri = $this->fetchUrl($path, $page, $limit); + + foreach ($filters as $key => $value) { + $uri->setVar($key, $value); + } + + return $this->processResponse($this->client->get($uri)); + } + + /** + * Get a subscription plan for an account (stubbed). + * + * Authenticate as the GitHub App with a JWT (see docs/apps.md). + * + * @param integer $accountId Account identifier. + * + * @return object + * + * @link https://docs.github.com/rest/apps/marketplace#get-a-subscription-plan-for-an-account-stubbed + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + public function getSubscriptionPlanForAccountStubbed(int $accountId) + { + // Build the request path. + $path = '/marketplace_listing/stubbed/accounts/' . $accountId; + + return $this->processResponse($this->client->get($this->fetchUrl($path))); + } + + /** + * List plans (stubbed). + * + * Authenticate as the GitHub App with a JWT (see docs/apps.md). + * + * @param integer $page The page number from which to get items. + * @param integer $limit The number of items on a page. + * + * @return array + * + * @link https://docs.github.com/rest/apps/marketplace#list-plans-stubbed + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + public function getListPlansStubbed(int $page = 0, int $limit = 0) + { + // Build the request path. + $path = '/marketplace_listing/stubbed/plans'; + + return $this->processResponse($this->client->get($this->fetchUrl($path, $page, $limit))); + } + + /** + * List accounts for a plan (stubbed). + * + * Authenticate as the GitHub App with a JWT (see docs/apps.md). + * + * @param integer $planId Plan identifier. + * @param array $filters Optional query parameters: sort, direction. + * @param integer $page The page number from which to get items. + * @param integer $limit The number of items on a page. + * + * @return array + * + * @link https://docs.github.com/rest/apps/marketplace#list-accounts-for-a-plan-stubbed + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + public function getListAccountsForPlanStubbed(int $planId, array $filters = [], int $page = 0, int $limit = 0) + { + // Build the request path. + $path = '/marketplace_listing/stubbed/plans/' . $planId . '/accounts'; + + $uri = $this->fetchUrl($path, $page, $limit); + + foreach ($filters as $key => $value) { + $uri->setVar($key, $value); + } + + return $this->processResponse($this->client->get($uri)); + } + + /** + * List subscriptions for the authenticated user. + * + * Authenticate with a user access token. + * + * @param integer $page The page number from which to get items. + * @param integer $limit The number of items on a page. + * + * @return array + * + * @link https://docs.github.com/rest/apps/marketplace#list-subscriptions-for-the-authenticated-user + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + public function getListSubscriptionsForAuthenticatedUser(int $page = 0, int $limit = 0) + { + // Build the request path. + $path = '/user/marketplace_purchases'; + + return $this->processResponse($this->client->get($this->fetchUrl($path, $page, $limit))); + } + + /** + * List subscriptions for the authenticated user (stubbed). + * + * Authenticate with a user access token. + * + * @param integer $page The page number from which to get items. + * @param integer $limit The number of items on a page. + * + * @return array + * + * @link https://docs.github.com/rest/apps/marketplace#list-subscriptions-for-the-authenticated-user-stubbed + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + public function getListSubscriptionsForAuthenticatedUserStubbed(int $page = 0, int $limit = 0) + { + // Build the request path. + $path = '/user/marketplace_purchases/stubbed'; + + return $this->processResponse($this->client->get($this->fetchUrl($path, $page, $limit))); + } +} diff --git a/src/Package/Apps/OauthApplications.php b/src/Package/Apps/OauthApplications.php new file mode 100644 index 00000000..1cf7d1ec --- /dev/null +++ b/src/Package/Apps/OauthApplications.php @@ -0,0 +1,119 @@ + $accessToken]); + + $this->processResponse($this->client->delete($this->fetchUrl($path), [], null, $data), 204); + } + + /** + * Check a token. + * + * Authenticate with Basic auth, the client ID as user name and the client secret as password (see docs/apps.md). + * + * @param string $clientId Client ID of the GitHub App or OAuth app. + * @param string $accessToken The OAuth access token. + * + * @return object + * + * @link https://docs.github.com/rest/apps/oauth-applications#check-a-token + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + public function checkToken(string $clientId, string $accessToken) + { + // Build the request path. + $path = '/applications/' . $clientId . '/token'; + + $data = json_encode(['access_token' => $accessToken]); + + return $this->processResponse($this->client->post($this->fetchUrl($path), $data)); + } + + /** + * Reset a token. + * + * Authenticate with Basic auth, the client ID as user name and the client secret as password (see docs/apps.md). + * + * @param string $clientId Client ID of the GitHub App or OAuth app. + * @param string $accessToken The OAuth access token. + * + * @return object + * + * @link https://docs.github.com/rest/apps/oauth-applications#reset-a-token + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + public function resetToken(string $clientId, string $accessToken) + { + // Build the request path. + $path = '/applications/' . $clientId . '/token'; + + $data = json_encode(['access_token' => $accessToken]); + + return $this->processResponse($this->client->patch($this->fetchUrl($path), $data)); + } + + /** + * Delete an app token. + * + * Authenticate with Basic auth, the client ID as user name and the client secret as password (see docs/apps.md). + * + * @param string $clientId Client ID of the GitHub App or OAuth app. + * @param string $accessToken The OAuth access token. + * + * @return void + * + * @link https://docs.github.com/rest/apps/oauth-applications#delete-an-app-token + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + public function deleteToken(string $clientId, string $accessToken) + { + // Build the request path. + $path = '/applications/' . $clientId . '/token'; + + $data = json_encode(['access_token' => $accessToken]); + + $this->processResponse($this->client->delete($this->fetchUrl($path), [], null, $data), 204); + } +} diff --git a/src/Package/Apps/Webhooks.php b/src/Package/Apps/Webhooks.php new file mode 100644 index 00000000..825e0f53 --- /dev/null +++ b/src/Package/Apps/Webhooks.php @@ -0,0 +1,139 @@ +processResponse($this->client->get($this->fetchUrl($path))); + } + + /** + * Update a webhook configuration for an app. + * + * Authenticate as the GitHub App with a JWT (see docs/apps.md). + * + * @param array $options Optional request body fields: url, content_type, secret, insecure_ssl. + * + * @return object + * + * @link https://docs.github.com/rest/apps/webhooks#update-a-webhook-configuration-for-an-app + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + public function editConfig(array $options = []) + { + // Build the request path. + $path = '/app/hook/config'; + + $data = json_encode((object) $options); + + return $this->processResponse($this->client->patch($this->fetchUrl($path), $data)); + } + + /** + * List deliveries for an app webhook. + * + * Authenticate as the GitHub App with a JWT (see docs/apps.md). + * + * This endpoint uses cursor-based pagination: pass the `cursor` filter from the `Link` header; + * GitHub ignores `$page`, only `$limit` (per_page) is used. + * + * @param array $filters Optional query parameters: cursor, status. + * @param integer $page The page number from which to get items. + * @param integer $limit The number of items on a page. + * + * @return array + * + * @link https://docs.github.com/rest/apps/webhooks#list-deliveries-for-an-app-webhook + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + public function getListDeliveries(array $filters = [], int $page = 0, int $limit = 0) + { + // Build the request path. + $path = '/app/hook/deliveries'; + + $uri = $this->fetchUrl($path, $page, $limit); + + foreach ($filters as $key => $value) { + $uri->setVar($key, $value); + } + + return $this->processResponse($this->client->get($uri)); + } + + /** + * Get a delivery for an app webhook. + * + * Authenticate as the GitHub App with a JWT (see docs/apps.md). + * + * @param integer $deliveryId Webhook delivery identifier. + * + * @return object + * + * @link https://docs.github.com/rest/apps/webhooks#get-a-delivery-for-an-app-webhook + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + public function getDelivery(int $deliveryId) + { + // Build the request path. + $path = '/app/hook/deliveries/' . $deliveryId; + + return $this->processResponse($this->client->get($this->fetchUrl($path))); + } + + /** + * Redeliver a delivery for an app webhook. + * + * Authenticate as the GitHub App with a JWT (see docs/apps.md). + * + * @param integer $deliveryId Webhook delivery identifier. + * + * @return object + * + * @link https://docs.github.com/rest/apps/webhooks#redeliver-a-delivery-for-an-app-webhook + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + public function redeliver(int $deliveryId) + { + // Build the request path. + $path = '/app/hook/deliveries/' . $deliveryId . '/attempts'; + + return $this->processResponse($this->client->post($this->fetchUrl($path), ''), 202); + } +}