✨ Webhook Callbacks endpoint CRUD methods

Adding callbacks resource for registering and managing webhooks. This
provides the basic CRUD operations. Verification and resending methods
to follow.

See Issue#44

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## Unreleased
 
+- Added Webhook Callback resource
 - Remove warnings in PHP 8.2
 - Handle new API version accounting errors
 

src/FreshBooksClient.php

@@ -16,6 +16,8 @@
 use Psr\Http\Message\StreamFactoryInterface;
 use amcintosh\FreshBooks\Exception\FreshBooksClientConfigException;
 use amcintosh\FreshBooks\Model\AuthorizationToken;
+use amcintosh\FreshBooks\Model\Callback;
+use amcintosh\FreshBooks\Model\CallbackList;
 use amcintosh\FreshBooks\Model\Client;
 use amcintosh\FreshBooks\Model\ClientList;
 use amcintosh\FreshBooks\Model\Expense;
@@ -37,6 +39,7 @@
 use amcintosh\FreshBooks\Model\TaxList;
 use amcintosh\FreshBooks\Resource\AccountingResource;
 use amcintosh\FreshBooks\Resource\AuthResource;
+use amcintosh\FreshBooks\Resource\EventsResource;
 use amcintosh\FreshBooks\Resource\ProjectResource;
 
 class FreshBooksClient
@@ -302,6 +305,17 @@ public function taxes(): AccountingResource
         return new AccountingResource($this->httpClient, 'taxes/taxes', Tax::class, TaxList::class);
     }
 
+    /**
+     * FreshBooks callbacks (webhook callbacks) resource with calls to
+     * get, list, create, update, delete, resend_verification, verify
+     *
+     * @return EventsResource
+     */
+    public function callbacks(): EventsResource
+    {
+        return new EventsResource($this->httpClient, 'events/callbacks', Callback::class, CallbackList::class);
+    }
+
     /**
      * FreshBooks projects resource with calls to get, list, create, update, delete.
      *

src/Model/Callback.php

@@ -0,0 +1,73 @@
+<?php
+
+declare(strict_types=1);
+
+namespace amcintosh\FreshBooks\Model;
+
+use DateTimeImmutable;
+use Spatie\DataTransferObject\Attributes\CastWith;
+use Spatie\DataTransferObject\Attributes\MapFrom;
+use Spatie\DataTransferObject\Attributes\MapTo;
+use Spatie\DataTransferObject\Caster;
+use Spatie\DataTransferObject\DataTransferObject;
+use amcintosh\FreshBooks\Model\Caster\ISODateTimeImmutableCaster;
+use amcintosh\FreshBooks\Model\DataModel;
+
+/**
+ * Webhook callback subscription model.
+ *
+ * @package amcintosh\FreshBooks\Model
+ * @link https://www.freshbooks.com/api/webhooks
+ */
+class Callback extends DataTransferObject implements DataModel
+{
+    public const RESPONSE_FIELD = 'callback';
+
+    /**
+     * @var int Get the unique identifier of this callback within this business.
+     */
+    #[MapFrom('callbackid')]
+    public ?int $callbackId;
+
+    /**
+     * @var string The event to register the webhook callback for (eg. `invoice.create`).
+     */
+    public ?string $event;
+
+    /**
+     * @var DateTimeImmutable The time of last modification.
+     */
+    #[MapFrom('updated_at')]
+    #[CastWith(ISODateTimeImmutableCaster::class)]
+    public ?DateTimeImmutable $updatedAt;
+
+    /**
+     * @var string The URI to send the webhook callback to.
+     */
+    public ?string $uri;
+
+    /**
+     * @var bool Whether the callback has been verified against the URI.
+     */
+    public ?bool $verified;
+
+    /**
+     * Get the data as an array to POST or PUT to FreshBooks, removing any read-only fields.
+     *
+     * @return array
+     */
+    public function getContent(): array
+    {
+        $data = $this
+            ->except('callbackId')
+            ->except('updatedAt')
+            ->except('verified')
+            ->toArray();
+        foreach ($data as $key => $value) {
+            if (is_null($value)) {
+                unset($data[$key]);
+            }
+        }
+        return $data;
+    }
+}

src/Model/CallbackList.php

@@ -0,0 +1,24 @@
+<?php
+
+declare(strict_types=1);
+
+namespace amcintosh\FreshBooks\Model;
+
+use Spatie\DataTransferObject\Attributes\CastWith;
+use Spatie\DataTransferObject\Casters\ArrayCaster;
+use amcintosh\FreshBooks\Model\AccountingList;
+use amcintosh\FreshBooks\Model\Callback;
+
+/**
+ * Results of callbacks list call containing list of callbacks and pagination data.
+ *
+ * @package amcintosh\FreshBooks\Model
+ * @link https://www.freshbooks.com/api/webhooks
+ */
+class CallbackList extends AccountingList
+{
+    public const RESPONSE_FIELD = 'callbacks';
+
+    #[CastWith(ArrayCaster::class, itemType: Callback::class)]
+    public array $callbacks;
+}

src/Resource/AccountingResource.php

@@ -15,12 +15,12 @@
 
 class AccountingResource extends BaseResource
 {
-    private HttpClient $httpClient;
-    private string $accountingPath;
-    private string $singleModel;
-    private string $listModel;
-    private bool $deleteViaUpdate;
-    private ?array $missingEndpoints;
+    protected HttpClient $httpClient;
+    protected string $accountingPath;
+    protected string $singleModel;
+    protected string $listModel;
+    protected bool $deleteViaUpdate;
+    protected ?array $missingEndpoints;
 
     public function __construct(
         HttpClient $httpClient,
@@ -45,7 +45,7 @@ public function __construct(
      * @param  int $resourceId
      * @return string
      */
-    private function getUrl(string $accountId, int $resourceId = null): string
+    protected function getUrl(string $accountId, int $resourceId = null): string
     {
         if (!is_null($resourceId)) {
             return "/accounting/account/{$accountId}/{$this->accountingPath}/{$resourceId}";
@@ -127,6 +127,7 @@ private function createOldResponseError(int $statusCode, array $responseData, st
     private function createNewResponseError(int $statusCode, array $responseData, string $rawRespone): void
     {
         $message = $responseData['message'];
+        $errorCode = null;
         $details = [];
 
         foreach ($responseData['details'] as $detail) {
@@ -151,7 +152,7 @@ private function createNewResponseError(int $statusCode, array $responseData, st
      * @param  string $rawRespone The raw response body
      * @return void
      */
-    private function handleError(int $statusCode, array $responseData, string $rawRespone): void
+    protected function handleError(int $statusCode, array $responseData, string $rawRespone): void
     {
         if (array_key_exists('response', $responseData) && array_key_exists('errors', $responseData['response'])) {
             $this->createOldResponseError($statusCode, $responseData, $rawRespone);

src/Resource/EventsResource.php

@@ -0,0 +1,67 @@
+<?php
+
+declare(strict_types=1);
+
+namespace amcintosh\FreshBooks\Resource;
+
+use Http\Client\HttpClient;
+use Spatie\DataTransferObject\DataTransferObject;
+use amcintosh\FreshBooks\Builder\IncludesBuilder;
+use amcintosh\FreshBooks\Exception\FreshBooksException;
+use amcintosh\FreshBooks\Exception\FreshBooksNotImplementedException;
+use amcintosh\FreshBooks\Model\DataModel;
+use amcintosh\FreshBooks\Model\ListModel;
+use amcintosh\FreshBooks\Model\VisState;
+
+/**
+ * Resource for calls to /events endpoints.
+ *
+ * @package amcintosh\FreshBooks\Resource
+ */
+class EventsResource extends AccountingResource
+{
+    /**
+     * The the url to the events resource.
+     *
+     * @param  string $accountId
+     * @param  int $resourceId
+     * @return string
+     */
+    protected function getUrl(string $accountId, int $resourceId = null): string
+    {
+        if (!is_null($resourceId)) {
+            return "/events/account/{$accountId}/{$this->accountingPath}/{$resourceId}";
+        }
+        return "/events/account/{$accountId}/{$this->accountingPath}";
+    }
+
+    /**
+     * Create a FreshBooksException from the json response from the events endpoint.
+     *
+     * @param  int $statusCode HTTP status code
+     * @param  array $responseData The json-parsed response
+     * @param  string $rawRespone The raw response body
+     * @return void
+     */
+    protected function handleError(int $statusCode, array $responseData, string $rawRespone): void
+    {
+        if (!array_key_exists('message', $responseData) || !array_key_exists('code', $responseData)) {
+            throw new FreshBooksException('Unknown error', $statusCode, null, $rawRespone);
+        }
+
+        $message = $responseData['message'];
+        $errorCode = null;
+        $details = [];
+
+        foreach ($responseData['details'] as $detail) {
+            if (
+                in_array('type.googleapis.com/google.rpc.BadRequest', $detail)
+                && array_key_exists('fieldViolations', $detail)
+            ) {
+                $details = $detail['fieldViolations'];
+            }
+        }
+        var_dump($details);
+        throw new FreshBooksException($message, $statusCode, null, $rawRespone, $errorCode, $details);
+    }
+}

tests/Model/CallbackTest.php

@@ -0,0 +1,42 @@
+<?php
+
+declare(strict_types=1);
+
+namespace amcintosh\FreshBooks\Tests\Model;
+
+use DateTime;
+use PHPUnit\Framework\TestCase;
+use amcintosh\FreshBooks\Model\Callback;
+
+final class CallbackTest extends TestCase
+{
+    private $sampleCallbackData = '{"callback":{
+        "callbackid": 123,
+        "verified": true,
+        "uri": "http://freshbooks.com/hook/123",
+        "event": "invoice.create",
+        "updated_at": "2017-08-23T11:45:09Z"}}';
+
+    public function testCallbackFromResponse(): void
+    {
+        $callbackData = json_decode($this->sampleCallbackData, true);
+
+        $callback = new Callback($callbackData[Callback::RESPONSE_FIELD]);
+
+        $this->assertSame(123, $callback->callbackId);
+        $this->assertSame('invoice.create', $callback->event);
+        $this->assertEquals(new DateTime('2017-08-23T11:45:09Z'), $callback->updatedAt);
+        $this->assertSame('http://freshbooks.com/hook/123', $callback->uri);
+        $this->assertTrue($callback->verified);
+    }
+
+    public function testCallbackGetContent(): void
+    {
+        $callbackData = json_decode($this->sampleCallbackData, true);
+        $callback = new Callback($callbackData['callback']);
+        $this->assertSame([
+            'event' => 'invoice.create',
+            'uri' => 'http://freshbooks.com/hook/123'
+        ], $callback->getContent());
+    }
+}