Merge pull request #62 from packagist/vendor-bundles-api

API: add endpoints to manage vendor bundles

README.md

@@ -39,6 +39,18 @@
             * [Grant a customer access to a package or edit the limitations](#grant-a-customer-access-to-a-package-or-edit-the-limitations)
             * [Revoke access to a package from a customer](#revoke-access-to-a-package-from-a-customer)
             * [Regenerate a customer's Composer repository token](#regenerate-a-customers-composer-repository-token)
+            * [List a customer's vendor bundles](#list-a-customers-vendor-bundles)
+            * [Grant a customer access to a vendor bundle or edit the limitations](#grant-a-customer-access-to-a-vendor-bundle-or-edit-the-limitations)
+            * [Revoke access to a vendor bundle from a customer](#revoke-access-to-a-vendor-bundle-from-a-customer)
+         * [Vendor Bundle](#vendor-bundle)
+            * [List an organization's vendor bundles](#list-an-organizations-vendor-bundles)
+            * [Show a vendor bundle](#show-a-vendor-bundle)
+            * [Create a vendor bundle](#create-a-vendor-bundle)
+            * [Edit a customer](#edit-a-customer-1)
+            * [Delete a vendor bundle](#delete-a-vendor-bundle)
+            * [List packages in a vendor bundle](#list-packages-in-a-vendor-bundle)
+            * [Add one or more packages to a vendor bundle or edit their limitations](#add-one-or-more-packages-to-a-vendor-bundle-or-edit-their-limitations)
+            * [Remove a package from a vendor bundle](#remove-a-package-from-a-vendor-bundle)
          * [Subrepository](#subrepository)
             * [List an organization's subrepositories](#list-an-organizations-subrepositories)
             * [Show a subrepository](#show-a-subrepository)
@@ -114,7 +126,7 @@
          * [Validate incoming webhook payloads](#validate-incoming-webhook-payloads)
       * [License](#license)
 
-<!-- Added by: glaubinix, at: Tue 24 Jan 2023 14:03:21 GMT -->
+<!-- Added by: glaubinix, at: Thu  9 Feb 2023 15:40:34 GMT -->
 
 <!--te-->
 
@@ -414,6 +426,100 @@ $composerRepository = $client->customers()->regenerateToken($customerId, $confir
 ```
 Returns the edited Composer repository.
 
+#### List a customer's vendor bundles
+```php
+$customerId = 42;
+$packages = $client->customers()->vendorBundles()->listVendorBundles($customerId);
+```
+Returns an array of customer vendor bundles.
+
+#### Grant a customer access to a vendor bundle or edit the limitations
+```php
+$customerId = 42;
+$vendorBundleId = 12;
+$expirationDate = (new \DateTime())->add(new \DateInterval('P1Y'))->format('c'), // optional expiration date to limit updates the customer receives
+$packages = $client->customers()->vendorBundles()->addOrEditVendorBundle($customerId, $vendorBundleId, $expirationDate);
+```
+Returns the added or edited customer vendor bundle.
+
+#### Revoke access to a vendor bundle from a customer
+```php
+$customerId = 42;
+$vendorBundleId = 12;
+$client->customers()->vendorBundles()->removeVendorBundle($customerId, $vendorBundleId);
+```
+
+### Vendor Bundle
+
+#### List an organization's vendor bundles
+```php
+$vendorBundles = $client->vendorBundles()->all();
+```
+Returns an array of vendor bundles.
+
+#### Show a vendor bundle
+```php
+$vendorBundleId = 42;
+$vendorBundle = $client->vendorBundles()->show($vendorBundleId);
+```
+Returns a single vendor bundle.
+
+#### Create a vendor bundle
+```php
+$vendorBundle = $client->vendorBundles()->create('New bundle name');
+// or
+$vendorBundle = $client->vendorBundles()->create('New bundle name', 'dev', '^1.0', true, [123]);
+```
+Returns the vendor bundle.
+
+#### Edit a customer
+```php
+$vendorBundleId = 42;
+$vendorBundleData = [
+    'name' => 'Bundle name',
+    'minimumAccessibleStability' => 'dev', 
+    'versionConstraint' => '^1.0',
+    'assignAllPackages' => true,
+    'synchronizationIds' => [123], // A list of synchronization ids for which new packages should automatically be added to the bundle.
+];
+$vendorBundle = $client->vendorBundles()->edit($vendorBundleId, $vendorBundleData);
+```
+Returns the vendor bundle.
+
+#### Delete a vendor bundle
+```php
+$vendorBundleId = 42;
+$client->vendorBundles()->remove($vendorBundleId);
+```
+
+#### List packages in a vendor bundle
+```php
+$vendorBundleId = 42;
+$packages = $client->vendorBundles()->packages()->listPackages($vendorBundleId);
+```
+Returns an array of vendor bundle packages.
+
+#### Add one or more packages to a vendor bundle or edit their limitations
+```php
+$vendorBundleId = 42;
+$packages = [
+    [
+        'name' => 'acme-website/package',
+        'versionConstraint' => '^1.0 | ^2.0', // optional version constraint to limit updates the customer receives
+        'minimumAccessibleStability' => 'beta', // optional stability to restrict customers to specific package version stabilities like alpha, beta, or RC
+    ],
+];
+$packages = $client->vendorBundles()->packages()->addOrEditPackages($vendorBundleId, $packages);
+```
+Returns an array of all added or edited customer packages.
+
+#### Remove a package from a vendor bundle
+```php
+$vendorBundleId = 42;
+$packageName = 'acme-website/package';
+$client->vendorBundles()->packages()->removePackage($vendorBundleId, $packageName);
+```
+
 ### Subrepository
 
 #### List an organization's subrepositories

src/Api/Customers.php

@@ -122,4 +122,9 @@ public function magentoLegacyKeys()
     {
         return new MagentoLegacyKeys($this->client);
     }
+
+    public function vendorBundles()
+    {
+        return new \PrivatePackagist\ApiClient\Api\Customers\VendorBundles($this->client);
+    }
 }

src/Api/Customers/VendorBundles.php

@@ -0,0 +1,42 @@
+<?php
+
+/*
+ * (c) Packagist Conductors GmbH <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace PrivatePackagist\ApiClient\Api\Customers;
+
+use PrivatePackagist\ApiClient\Api\AbstractApi;
+
+class VendorBundles extends AbstractApi
+{
+    public function listVendorBundles($customerIdOrUrlName)
+    {
+        return $this->get(sprintf('/customers/%s/vendor-bundles/', $customerIdOrUrlName));
+    }
+
+    /**
+     * @param int|string $customerIdOrUrlName
+     * @param int $vendorBundleId
+     * @param null|string $expirationDate
+     */
+    public function addOrEditVendorBundle($customerIdOrUrlName, $vendorBundleId, $expirationDate = null)
+    {
+        return $this->post(sprintf('/customers/%s/vendor-bundles/', $customerIdOrUrlName), [
+            'vendorBundleId' => $vendorBundleId,
+            'expirationDate' => $expirationDate,
+        ]);
+    }
+
+    /**
+     * @param int|string $customerIdOrUrlName
+     * @param int $vendorBundleId
+     */
+    public function removeVendorBundle($customerIdOrUrlName, $vendorBundleId)
+    {
+        return $this->delete(sprintf('/customers/%s/vendor-bundles/%s/', $customerIdOrUrlName, $vendorBundleId));
+    }
+}

src/Api/Synchronizations.php

@@ -1,5 +1,12 @@
 <?php
 
+/*
+ * (c) Packagist Conductors GmbH <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
 namespace PrivatePackagist\ApiClient\Api;
 
 class Synchronizations extends AbstractApi

src/Api/VendorBundles.php

@@ -0,0 +1,71 @@
+<?php
+
+/*
+ * (c) Packagist Conductors GmbH <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace PrivatePackagist\ApiClient\Api;
+
+class VendorBundles extends AbstractApi
+{
+    /**
+     * @return array[]
+     */
+    public function all()
+    {
+        return $this->get('/vendor-bundles/');
+    }
+
+    /**
+     * @param int $vendorBundleId
+     * @return array
+     */
+    public function show($vendorBundleId)
+    {
+        return $this->get(sprintf('/vendor-bundles/%s/', $vendorBundleId));
+    }
+
+    /**
+     * @param string $name
+     * @param string|null $minimumAccessibleStability
+     * @param string|null $versionConstraint
+     * @param bool $assignAllPackages
+     * @param int[] $synchronizationIds
+     */
+    public function create($name, $minimumAccessibleStability = null, $versionConstraint = null, $assignAllPackages = false, array $synchronizationIds = [])
+    {
+        return $this->post('/vendor-bundles/', [
+            'name' => $name,
+            'minimumAccessibleStability' => $minimumAccessibleStability,
+            'versionConstraint' => $versionConstraint,
+            'assignAllPackages' => $assignAllPackages,
+            'synchronizationIds' => $synchronizationIds,
+        ]);
+    }
+
+    /**
+     * @param int $vendorBundleId
+     * @param array{name: string, minimumAccessibleStability?: string, versionConstraint?: string, assignAllPackages: bool, synchronizationIds?: int[]} $bundle
+     * @return array
+     */
+    public function edit($vendorBundleId, array $bundle)
+    {
+        return $this->put(sprintf('/vendor-bundles/%s/', $vendorBundleId), $bundle);
+    }
+
+    /**
+     * @param int $vendorBundleId
+     */
+    public function remove($vendorBundleId)
+    {
+        return $this->delete(sprintf('/vendor-bundles/%s/', $vendorBundleId));
+    }
+
+    public function packages(): \PrivatePackagist\ApiClient\Api\VendorBundles\Packages
+    {
+        return new \PrivatePackagist\ApiClient\Api\VendorBundles\Packages($this->client);
+    }
+}

src/Api/VendorBundles/Packages.php

@@ -0,0 +1,50 @@
+<?php
+
+/*
+ * (c) Packagist Conductors GmbH <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace PrivatePackagist\ApiClient\Api\VendorBundles;
+
+use PrivatePackagist\ApiClient\Api\AbstractApi;
+use PrivatePackagist\ApiClient\Exception\InvalidArgumentException;
+
+class Packages extends AbstractApi
+{
+    /**
+     * @param int $vendorBundleIds
+     * @return array[]
+     */
+    public function listPackages($vendorBundleIds)
+    {
+        return $this->get(sprintf('/vendor-bundles/%s/packages/', $vendorBundleIds));
+    }
+
+    /**
+     * @param int $vendorBundleId
+     * @param array{name: string, versionConstraint?: string, minimumAccessibleStability?: string}[] $packages
+     * @return array[]
+     */
+    public function addOrEditPackages($vendorBundleId, array $packages)
+    {
+        foreach ($packages as $package) {
+            if (!isset($package['name'])) { // @phpstan-ignore-line
+                throw new InvalidArgumentException('Parameter "name" is required.');
+            }
+        }
+
+        return $this->post(sprintf('/vendor-bundles/%s/packages/', $vendorBundleId), $packages);
+    }
+
+    /**
+     * @param int $vendorBundleId
+     * @param string $packageName
+     */
+    public function removePackage($vendorBundleId, $packageName)
+    {
+        return $this->delete(sprintf('/vendor-bundles/%s/packages/%s/', $vendorBundleId, $packageName));
+    }
+}

src/Client.php

@@ -117,6 +117,11 @@ public function synchronizations()
         return new Api\Synchronizations($this, $this->responseMediator);
     }
 
+    public function vendorBundles()
+    {
+        return new Api\VendorBundles($this, $this->responseMediator);
+    }
+
     public function getHttpClient()
     {
         return $this->getHttpClientBuilder()->getHttpClient();

tests/Api/Customers/VendorBundlesTest.php

@@ -0,0 +1,67 @@
+<?php declare(strict_types=1);
+
+namespace PrivatePackagist\ApiClient\Api\Customers;
+
+use PHPUnit\Framework\MockObject\MockObject;
+use PrivatePackagist\ApiClient\Api\ApiTestCase;
+
+class VendorBundlesTest extends ApiTestCase
+{
+    public function testListVendorBundles()
+    {
+        $expected = [
+            [
+                'expirationDate' => null,
+                'vendorBundle' => ['id' => 12],
+            ],
+        ];
+
+        /** @var VendorBundles&MockObject $api */
+        $api = $this->getApiMock();
+        $api->expects($this->once())
+            ->method('get')
+            ->with($this->equalTo('/customers/1/vendor-bundles/'))
+            ->willReturn($expected);
+
+        $this->assertSame($expected, $api->listVendorBundles(1));
+    }
+
+    public function testAddOrEditVendorBundle()
+    {
+        $expected = [
+            'expirationDate' => null,
+            'vendorBundle' => ['id' => 12],
+        ];
+
+        /** @var VendorBundles&MockObject $api */
+        $api = $this->getApiMock();
+        $api->expects($this->once())
+            ->method('post')
+            ->with($this->equalTo('/customers/1/vendor-bundles/'), $this->equalTo([
+                'vendorBundleId' => 12,
+                'expirationDate' => null,
+            ]))
+            ->willReturn($expected);
+
+        $this->assertSame($expected, $api->addOrEditVendorBundle(1, 12));
+    }
+
+    public function testRemoveVendorBundle()
+    {
+        $expected = '';
+
+        /** @var VendorBundles&MockObject $api */
+        $api = $this->getApiMock();
+        $api->expects($this->once())
+            ->method('delete')
+            ->with($this->equalTo(sprintf('/customers/1/vendor-bundles/%s/', 12)))
+            ->willReturn($expected);
+
+        $this->assertSame($expected, $api->removeVendorBundle(1, 12));
+    }
+
+    protected function getApiClass()
+    {
+        return VendorBundles::class;
+    }
+}