feature #1142 Copilot Usage Endpoints (anthony-webart)

This PR was squashed before being merged into the 3.14-dev branch.

Discussion
----------



Commits
-------

f4e822e Add Copilot usage endpoints
e16a14c Reformat code
3698933 Fix incorrect team urls
956fe9e Add Copilot Usage API Documentation detailing endpoints for retrieving usage summaries.

Author: anthony-webart

doc/copilot/usage.md

@@ -0,0 +1,80 @@
+# Copilot Usage API Documentation
+[Back to the navigation](../README.md)
+
+## Overview
+
+The Copilot Usage API provides endpoints to retrieve usage summaries for organizations and enterprises.
+
+**Note**: This endpoint is in beta and is subject to change.
+
+## Endpoints
+
+### Organization Usage Summary
+
+Retrieve the usage summary for a specific organization.
+
+**Method:** `GET`
+
+**Endpoint:** `/orgs/{organization}/copilot/usage`
+
+**Parameters:**
+- `organization` (string): The name of the organization.
+- `params` (array, optional): Additional query parameters.
+
+**Example:**
+```php
+$usage = $client->api('copilotUsage')->orgUsageSummary('KnpLabs');
+```
+
+### Organization Team Usage Summary
+
+Retrieve the usage summary for a specific team within an organization.
+
+**Method:** `GET`
+
+**Endpoint:** `/orgs/{organization}/team/{team}/copilot/usage`
+
+**Parameters:**
+- `organization` (string): The name of the organization.
+- `team` (string): The name of the team.
+- `params` (array, optional): Additional query parameters.
+
+**Example:**
+```php
+$usage = $client->api('copilotUsage')->orgTeamUsageSummary('KnpLabs', 'developers');
+```
+
+### Enterprise Usage Summary
+
+Retrieve the usage summary for a specific enterprise.
+
+**Method:** `GET`
+
+**Endpoint:** `/enterprises/{enterprise}/copilot/usage`
+
+**Parameters:**
+- `enterprise` (string): The name of the enterprise.
+- `params` (array, optional): Additional query parameters.
+
+**Example:**
+```php
+$usage = $client->api('copilotUsage')->enterpriseUsageSummary('KnpLabs');
+```
+
+### Enterprise Team Usage Summary
+
+Retrieve the usage summary for a specific team within an enterprise.
+
+**Method:** `GET`
+
+**Endpoint:** `/enterprises/{enterprise}/team/{team}/copilot/usage`
+
+**Parameters:**
+- `enterprise` (string): The name of the enterprise.
+- `team` (string): The name of the team.
+- `params` (array, optional): Additional query parameters.
+
+**Example:**
+```php
+$usage = $client->api('copilotUsage')->enterpriseTeamUsageSummary('KnpLabs', 'developers');
+```

lib/Github/Api/Copilot/Usage.php

@@ -0,0 +1,34 @@
+<?php
+
+namespace Github\Api\Copilot;
+
+use Github\Api\AbstractApi;
+
+class Usage extends AbstractApi
+{
+    public function orgUsageSummary(string $organization, array $params = []): array
+    {
+        return $this->get('/orgs/'.rawurlencode($organization).'/copilot/usage', $params);
+    }
+
+    public function orgTeamUsageSummary(string $organization, string $teamSlug, array $params = []): array
+    {
+        return $this->get(
+            '/orgs/'.rawurlencode($organization).'/team/'.rawurlencode($teamSlug).'/copilot/usage',
+            $params
+        );
+    }
+
+    public function enterpriseUsageSummary(string $enterprise, array $params = []): array
+    {
+        return $this->get('/enterprises/'.rawurlencode($enterprise).'/copilot/usage', $params);
+    }
+
+    public function enterpriseTeamUsageSummary(string $enterprise, string $teamSlug, array $params = []): array
+    {
+        return $this->get(
+            '/enterprises/'.rawurlencode($enterprise).'/team/'.rawurlencode($teamSlug).'/copilot/usage',
+            $params
+        );
+    }
+}

lib/Github/Client.php

@@ -301,6 +301,11 @@ public function api($name): AbstractApi
                 $api = new Api\Organization\OutsideCollaborators($this);
                 break;
 
+            case 'copilotUsage':
+            case 'copilot_usage':
+                $api = new Api\Copilot\Usage($this);
+                break;
+
             default:
                 throw new InvalidArgumentException(sprintf('Undefined api instance called: "%s"', $name));
         }

test/Github/Tests/Api/Copilot/UsageTest.php

@@ -0,0 +1,78 @@
+<?php
+
+namespace Github\Tests\Api\Copilot;
+
+use Github\Api\Copilot\Usage;
+use Github\Tests\Api\TestCase;
+
+class UsageTest extends TestCase
+{
+    /**
+     * @test
+     */
+    public function shouldGetOrgUsageSummary(): void
+    {
+        $expectedValue = ['usage1', 'usage2'];
+
+        $api = $this->getApiMock();
+        $api->expects($this->once())
+            ->method('get')
+            ->with('/orgs/KnpLabs/copilot/usage', [])
+            ->will($this->returnValue($expectedValue));
+
+        $this->assertEquals($expectedValue, $api->orgUsageSummary('KnpLabs'));
+    }
+
+    /**
+     * @test
+     */
+    public function shouldGetOrgTeamUsageSummary(): void
+    {
+        $expectedValue = ['usage1', 'usage2'];
+
+        $api = $this->getApiMock();
+        $api->expects($this->once())
+            ->method('get')
+            ->with('/orgs/KnpLabs/team/php-github-api/copilot/usage', [])
+            ->will($this->returnValue($expectedValue));
+
+        $this->assertEquals($expectedValue, $api->orgTeamUsageSummary('KnpLabs', 'php-github-api'));
+    }
+
+    /**
+     * @test
+     */
+    public function shouldGetEnterpriseUsageSummary(): void
+    {
+        $expectedValue = ['usage1', 'usage2'];
+
+        $api = $this->getApiMock();
+        $api->expects($this->once())
+            ->method('get')
+            ->with('/enterprises/KnpLabs/copilot/usage', [])
+            ->will($this->returnValue($expectedValue));
+
+        $this->assertEquals($expectedValue, $api->enterpriseUsageSummary('KnpLabs'));
+    }
+
+    /**
+     * @test
+     */
+    public function shouldGetEnterpriseTeamUsageSummary(): void
+    {
+        $expectedValue = ['usage1', 'usage2'];
+
+        $api = $this->getApiMock();
+        $api->expects($this->once())
+            ->method('get')
+            ->with('/enterprises/KnpLabs/team/php-github-api/copilot/usage', [])
+            ->will($this->returnValue($expectedValue));
+
+        $this->assertEquals($expectedValue, $api->enterpriseTeamUsageSummary('KnpLabs', 'php-github-api'));
+    }
+
+    protected function getApiClass(): string
+    {
+        return Usage::class;
+    }
+}