Release/1.12.0

RELEASE_NOTES.md

@@ -1,3 +1,8 @@
-### Fixes
 
-- Many deprecation notices for PHP 8.2 about creation of dynamic properties (#201)
+### Issues Fixed
+
+Allow null `meta_description` on Product (Thanks @macbookandrew)
+
+### New Features
+
+Adds support for Webhooks API (#187)

src/BigCommerce/Api/Webhooks/WebhookAdminApi.php

@@ -0,0 +1,41 @@
+<?php
+
+namespace BigCommerce\ApiV3\Api\Webhooks;
+
+use BigCommerce\ApiV3\Api\Generic\GetResource;
+use BigCommerce\ApiV3\Api\Generic\V3ApiBase;
+use BigCommerce\ApiV3\ResponseModels\Webhook\AdminInfoResponse;
+use GuzzleHttp\RequestOptions;
+
+class WebhookAdminApi extends V3ApiBase
+{
+    use GetResource;
+
+    public const WEBHOOK_ADMIN_ENDPOINT = 'hooks/admin';
+
+    public function singleResourceUrl(): string
+    {
+        return self::WEBHOOK_ADMIN_ENDPOINT;
+    }
+
+    public function get(?bool $isActive = null): AdminInfoResponse
+    {
+        $filter = is_null($isActive) ? [] : ['is_active' => $isActive];
+        return new AdminInfoResponse($this->getResource($filter));
+    }
+
+    /**
+     * Update email addresses that are sent notification emails when any domain associated with the API account
+     * is denylisted or when a webhook is deactivated. Supports upsert functionality in the case that no email
+     * address exists yet.
+     */
+    public function upsertEmails(array $emails): void
+    {
+        $this->getClient()->getRestClient()->put(
+            $this->singleResourceUrl(),
+            [
+                RequestOptions::JSON => ['emails' => $emails]
+            ]
+        );
+    }
+}

src/BigCommerce/Api/Webhooks/WebhookEventsApi.php

@@ -0,0 +1,27 @@
+<?php
+
+namespace BigCommerce\ApiV3\Api\Webhooks;
+
+use BigCommerce\ApiV3\Api\Generic\GetAllResources;
+use BigCommerce\ApiV3\Api\Generic\V3ApiBase;
+use BigCommerce\ApiV3\ResponseModels\Webhook\WebhookEventsResponse;
+
+class WebhookEventsApi extends V3ApiBase
+{
+    use GetAllResources;
+
+    public const EVENTS_ENDPOINT = 'hooks/events';
+
+    public function multipleResourceUrl(): string
+    {
+        return self::EVENTS_ENDPOINT;
+    }
+
+    /**
+     * Get a list of events that were sent but not successfully received. Events are stored for not less than one week
+     */
+    public function getAll(array $filters = [], int $page = 1, int $limit = 250): WebhookEventsResponse
+    {
+        return new WebhookEventsResponse($this->getAllResources($filters, $page, $limit));
+    }
+}

src/BigCommerce/Api/Webhooks/WebhooksApi.php

@@ -0,0 +1,64 @@
+<?php
+
+namespace BigCommerce\ApiV3\Api\Webhooks;
+
+use BigCommerce\ApiV3\Api\Generic\ResourceApi;
+use BigCommerce\ApiV3\ResourceModels\Webhook\Webhook;
+use BigCommerce\ApiV3\ResponseModels\Webhook\WebhookResponse;
+use BigCommerce\ApiV3\ResponseModels\Webhook\WebhooksResponse;
+
+class WebhooksApi extends ResourceApi
+{
+    public const WEBHOOK_ENDPOINT = 'hooks/%d';
+    public const WEBHOOKS_ENDPOINT = 'hooks';
+    public const RESOURCE_NAME = 'hooks';
+
+    public function get(): WebhookResponse
+    {
+        return new WebhookResponse($this->getResource());
+    }
+
+    /**
+     * Creates a webhook. Only one webhook at a time can be created. Custom headers can be added.
+     * Destination URL must be served on port 443 (custom ports are not currently supported).
+     */
+    public function create(Webhook $webhook): WebhookResponse
+    {
+        return new WebhookResponse($this->createResource($webhook));
+    }
+
+    public function update(Webhook $webhook): WebhookResponse
+    {
+        return new WebhookResponse($this->updateResource($webhook));
+    }
+
+    protected function singleResourceEndpoint(): string
+    {
+        return self::WEBHOOK_ENDPOINT;
+    }
+
+    protected function multipleResourcesEndpoint(): string
+    {
+        return self::WEBHOOKS_ENDPOINT;
+    }
+
+    protected function resourceName(): string
+    {
+        return self::RESOURCE_NAME;
+    }
+
+    public function getAll(array $filters = [], int $page = 1, int $limit = 250): WebhooksResponse
+    {
+        return new WebhooksResponse($this->getAllResources($filters, $page, $limit));
+    }
+
+    public function events(): WebhookEventsApi
+    {
+        return new WebhookEventsApi($this->getClient());
+    }
+
+    public function admin(): WebhookAdminApi
+    {
+        return new WebhookAdminApi($this->getClient());
+    }
+}

src/BigCommerce/Client.php

@@ -15,6 +15,7 @@
 use BigCommerce\ApiV3\Api\Sites\SitesApi;
 use BigCommerce\ApiV3\Api\StoreLogs\StoreLogsApi;
 use BigCommerce\ApiV3\Api\Themes\ThemesApi;
+use BigCommerce\ApiV3\Api\Webhooks\WebhooksApi;
 use BigCommerce\ApiV3\Api\Widgets\WidgetsApi;
 use BigCommerce\ApiV3\Api\CustomTemplateAssociations\CustomTemplateAssociationsApi;
 use BigCommerce\ApiV3\Api\Wishlists\WishlistsApi;
@@ -223,6 +224,16 @@ public function storeLogs(): StoreLogsApi
         return new StoreLogsApi($this);
     }
 
+    public function webhook(int $id): WebhooksApi
+    {
+        return new WebhooksApi($this, $id);
+    }
+
+    public function webhooks(): WebhooksApi
+    {
+        return new WebhooksApi($this);
+    }
+
     protected function defaultBaseUrl(): string
     {
         return self::API_URI;

src/BigCommerce/ResourceModels/Catalog/Product/Product.php

@@ -63,7 +63,7 @@ class Product extends ResourceModel
     public int $order_quantity_maximum;
     public string $page_title;
     public array $meta_keywords;
-    public string $meta_description;
+    public ?string $meta_description;
     public string $date_created;
     public string $date_modified;
     public int $view_count;

src/BigCommerce/ResourceModels/ResourceModel.php

@@ -54,6 +54,15 @@ protected function buildPropertyObject(string $property, string $className): voi
         }
     }
 
+    protected function buildHashArray(string $property): void
+    {
+        if (!is_null($this->optionObject) && isset($this->optionObject->$property)) {
+            $this->$property = (array) $this->optionObject->$property;
+
+            unset($this->optionObject->$property);
+        }
+    }
+
     /**
      * Override this function to implement custom build functionality
      */

src/BigCommerce/ResourceModels/Webhook/BlockedDomain.php

@@ -0,0 +1,22 @@
+<?php
+
+namespace BigCommerce\ApiV3\ResourceModels\Webhook;
+
+use BigCommerce\ApiV3\ResourceModels\ResourceModel;
+
+class BlockedDomain extends ResourceModel
+{
+    public string $destination;
+    public string $time_left;
+
+    /**
+     * @var BlockedDomainReason[]
+     */
+    public array $reasons;
+
+    protected function beforeBuildObject(): void
+    {
+        self::buildObjectArray('reasons', BlockedDomainReason::class);
+        parent::beforeBuildObject();
+    }
+}

src/BigCommerce/ResourceModels/Webhook/BlockedDomainReason.php

@@ -0,0 +1,12 @@
+<?php
+
+namespace BigCommerce\ApiV3\ResourceModels\Webhook;
+
+use BigCommerce\ApiV3\ResourceModels\ResourceModel;
+
+class BlockedDomainReason extends ResourceModel
+{
+    public string $failure_description;
+    public int $count;
+    public int $timestamp;
+}

src/BigCommerce/ResourceModels/Webhook/Webhook.php

@@ -0,0 +1,24 @@
+<?php
+
+namespace BigCommerce\ApiV3\ResourceModels\Webhook;
+
+use BigCommerce\ApiV3\ResourceModels\ResourceModel;
+
+class Webhook extends ResourceModel
+{
+    public int $id;
+    public string $client_id;
+    public string $store_hash;
+    public string $scope;
+    public string $destination;
+    public ?array $headers;
+    public string $created_at;
+    public string $updated_at;
+    public bool $is_active;
+
+    protected function beforeBuildObject(): void
+    {
+        self::buildHashArray('headers');
+        parent::beforeBuildObject();
+    }
+}

src/BigCommerce/ResourceModels/Webhook/WebhookAdminInfo.php

@@ -0,0 +1,28 @@
+<?php
+
+namespace BigCommerce\ApiV3\ResourceModels\Webhook;
+
+use BigCommerce\ApiV3\ResourceModels\ResourceModel;
+
+class WebhookAdminInfo extends ResourceModel
+{
+    /**
+     * @var string[]
+     */
+    public array $emails;
+    /**
+     * @var Webhook[]
+     */
+    public array $hooks_list;
+    /**
+     * @var BlockedDomain[]
+     */
+    public array $blocked_domains;
+
+    protected function beforeBuildObject(): void
+    {
+        self::buildObjectArray('hooks_list', Webhook::class);
+        self::buildObjectArray('blocked_domains', BlockedDomain::class);
+        parent::beforeBuildObject();
+    }
+}

src/BigCommerce/ResourceModels/Webhook/WebhookEvent.php

@@ -0,0 +1,15 @@
+<?php
+
+namespace BigCommerce\ApiV3\ResourceModels\Webhook;
+
+use BigCommerce\ApiV3\ResourceModels\ResourceModel;
+
+class WebhookEvent extends ResourceModel
+{
+    public string $scope;
+    public string $store_id;
+    public object $data;
+    public string $hash;
+    public string $created_at;
+    public string $producer;
+}

src/BigCommerce/ResponseModels/Webhook/AdminInfoResponse.php

@@ -0,0 +1,22 @@
+<?php
+
+namespace BigCommerce\ApiV3\ResponseModels\Webhook;
+
+use BigCommerce\ApiV3\ResourceModels\Webhook\WebhookAdminInfo;
+use BigCommerce\ApiV3\ResponseModels\SingleResourceResponse;
+use stdClass;
+
+class AdminInfoResponse extends SingleResourceResponse
+{
+    private WebhookAdminInfo $adminInfo;
+
+    public function getAdminInfo(): WebhookAdminInfo
+    {
+        return $this->adminInfo;
+    }
+
+    protected function addData(stdClass $rawData): void
+    {
+        $this->adminInfo = new WebhookAdminInfo($rawData);
+    }
+}

src/BigCommerce/ResponseModels/Webhook/WebhookEventsResponse.php

@@ -0,0 +1,22 @@
+<?php
+
+namespace BigCommerce\ApiV3\ResponseModels\Webhook;
+
+use BigCommerce\ApiV3\ResourceModels\Webhook\WebhookEvent;
+use BigCommerce\ApiV3\ResponseModels\PaginatedResponse;
+
+class WebhookEventsResponse extends PaginatedResponse
+{
+    /**
+     * @return WebhookEvent[]
+     */
+    public function getEvents(): array
+    {
+        return $this->getData();
+    }
+
+    protected function resourceClass(): string
+    {
+        return WebhookEvent::class;
+    }
+}

src/BigCommerce/ResponseModels/Webhook/WebhookResponse.php

@@ -0,0 +1,22 @@
+<?php
+
+namespace BigCommerce\ApiV3\ResponseModels\Webhook;
+
+use BigCommerce\ApiV3\ResourceModels\Webhook\Webhook;
+use BigCommerce\ApiV3\ResponseModels\SingleResourceResponse;
+use stdClass;
+
+class WebhookResponse extends SingleResourceResponse
+{
+    private Webhook $webhook;
+
+    public function getWebhook(): Webhook
+    {
+        return $this->webhook;
+    }
+
+    protected function addData(stdClass $rawData): void
+    {
+        $this->webhook = new Webhook($rawData);
+    }
+}

src/BigCommerce/ResponseModels/Webhook/WebhooksResponse.php

@@ -0,0 +1,21 @@
+<?php
+
+namespace BigCommerce\ApiV3\ResponseModels\Webhook;
+
+use BigCommerce\ApiV3\ResourceModels\Webhook\Webhook;
+use BigCommerce\ApiV3\ResponseModels\PaginatedResponse;
+
+class WebhooksResponse extends PaginatedResponse
+{
+    /**
+     * @return Webhook[]
+     */
+    public function getWebhooks(): array
+    {
+        return $this->getData();
+    }
+    protected function resourceClass(): string
+    {
+        return Webhook::class;
+    }
+}