feat: add AuthenticationErrorException and add some documentation #29 (…

…#36)

* feat: add AuthenticationErrorException and add some documentation #29

* fix: add markdown fenced code block language

* fix: use constants for http codes

README.md

@@ -13,7 +13,7 @@ An small PHP library for Bluesky social using the AT Protocol.
 
 Installing using composer is suggested
 
-```
+```bash
 composer require potibm/phluesky
 ```
 
@@ -23,7 +23,7 @@ The HTTP service discovery will do the magic. In most cases no additional steps
 
 ### Setup and posting a simple message
 
-```
+```php
 $api = new \potibm\Bluesky\BlueskyApi('nick.bsky.social', 'abcd-efgh-ijkl-mnop');
 $postService = new \potibm\Bluesky\BlueskyPostService($api);
 
@@ -34,14 +34,14 @@ $response = $api->createRecord($post);
 
 ### Adding mentions and links from post text
 
-```
+```php
 $post = \potibm\Bluesky\Feed\Post::create('✨ example mentioning @atproto.com to share the URL 👨‍❤️‍👨 https://en.wikipedia.org/wiki/CBOR.');
 $post = $postService->addFacetsFromMentionsAndLinks($post);
 ```
 
 ### Adding mentions and links and tags from post text
 
-```
+```php
 $post = \potibm\Bluesky\Feed\Post::create('✨ example mentioning @atproto.com to share the URL 👨‍❤️‍👨 https://en.wikipedia.org/wiki/CBOR. and #HashtagFun');
 $post = $postService->addFacetsFromMentionsAndLinksAndTags($post);
 ```
@@ -50,7 +50,7 @@ $post = $postService->addFacetsFromMentionsAndLinksAndTags($post);
 
 [https://atproto.com/blog/create-post#images-embeds](https://atproto.com/blog/create-post#images-embeds)
 
-```
+```php
 $post = \potibm\Bluesky\Feed\Post::create('example post with image attached');
 $post = $postService->addImage(
     $post, 
@@ -63,7 +63,7 @@ $post = $postService->addImage(
 
 [https://atproto.com/blog/create-post#website-card-embeds](https://atproto.com/blog/create-post#website-card-embeds)
 
-```
+```php
 $post = \potibm\Bluesky\Feed\Post::create('post which embeds an external URL as a card');
 $post = $postService->addWebsiteCard(
     $post, 
@@ -78,7 +78,7 @@ $post = $postService->addWebsiteCard(
 
 [https://atproto.com/blog/create-post#replies](https://atproto.com/blog/create-post#replies)
 
-```
+```php
 $post = \potibm\Bluesky\Feed\Post::create('example of a reply');
 $post = $postService->addReply(
     $post, 
@@ -90,14 +90,35 @@ $post = $postService->addReply(
 
 [https://atproto.com/blog/create-post#quote-posts](https://atproto.com/blog/create-post#quote-posts)
 
-```
+```php
 $post = \potibm\Bluesky\Feed\Post::create('example of a quote-post');
 $post = $postService->addQuote(
     $post, 
     'at://did:plc:u5cwb2mwiv2bfq53cjufe6yn/app.bsky.feed.post/3k44deefqdk2g'
 );
 ```
 
+### Handling errors
+
+While performing requests using the API, exceptions may be thrown. 
+
+The exceptions are of the base type `potibm\Bluesky\Exception\Exception`.
+The exception message will contain details from the API.
+
+```php
+try {
+    $response = $api->createRecord($post);
+} catch (\potibm\Bluesky\Exception\HttpRequestException $e) {
+    echo 'Error performing request on HTTP level: ' . $e->getMessage();
+} catch (\potibm\Bluesky\Exception\AuthenticationErrorException $e) {
+    echo 'Unable to authorize: ' . $e->getMessage();
+} catch (\potibm\Bluesky\Exception\HttpStatusCodeException $e) {
+    echo 'Unable to perform request on API level: ' . $e->getMessage();
+} catch (\potibm\Bluesky\Exception\InvalidPayloadException $e) {
+    echo 'Received unserializable JSON payload: ' . $e->getMessage();
+}
+``` 
+
 ## License
 
 The MIT License (MIT). Please see [License File](https://github.com/potibm/phluesky/blob/main/LICENSE) for more information.

src/BlueskyApi.php

@@ -4,6 +4,7 @@
 
 namespace potibm\Bluesky;
 
+use potibm\Bluesky\Exception\AuthenticationErrorException;
 use potibm\Bluesky\Exception\HttpRequestException;
 use potibm\Bluesky\Exception\HttpStatusCodeException;
 use potibm\Bluesky\Exception\InvalidPayloadException;
@@ -17,6 +18,10 @@ class BlueskyApi implements BlueskyApiInterface
 {
     private const BASE_URL = 'https://bsky.social/';
 
+    private const HTTP_OK = 200;
+
+    private const HTTP_UNAUTHORIZED = 401;
+
     private ?CreateSessionResponse $session = null;
 
     public function __construct(
@@ -166,7 +171,9 @@ private function performXrpcCall(
             throw new HttpRequestException('Failed to send the request: ' . $e->getMessage());
         }
 
-        if ($response->getStatusCode() != 200) {
+        if ($response->getStatusCode() === self::HTTP_UNAUTHORIZED) {
+            throw new AuthenticationErrorException('Authentication failed: ' . (string) $response->getBody(), 401);
+        } elseif ($response->getStatusCode() != self::HTTP_OK) {
             throw new HttpStatusCodeException('Received an HTTP error (' . $response->getStatusCode() . '): ' . (string) $response->getBody(), $response->getStatusCode());
         }
 

src/Exception/AuthenticationErrorException.php

@@ -0,0 +1,9 @@
+<?php
+
+declare(strict_types=1);
+
+namespace potibm\Bluesky\Exception;
+
+class AuthenticationErrorException extends HttpStatusCodeException
+{
+}

tests/BlueskyApiTest.php

@@ -11,6 +11,7 @@
 use potibm\Bluesky\BlueskyApi;
 use potibm\Bluesky\BlueskyUri;
 use potibm\Bluesky\Embed\Images;
+use potibm\Bluesky\Exception\AuthenticationErrorException;
 use potibm\Bluesky\Exception\HttpRequestException;
 use potibm\Bluesky\Exception\HttpStatusCodeException;
 use potibm\Bluesky\Exception\InvalidPayloadException;
@@ -90,6 +91,21 @@ public function testGetDidForHandleMissingValue(): void
         $api->getDidForHandle('handle');
     }
 
+    public function testAuthenticationErrorOnCreateRecord(): void
+    {
+        $this->expectException(AuthenticationErrorException::class);
+
+        $post = Post::create('Test for a post');
+
+        $httpComponent = $this->generateHttpComponentsManager(401, true, [
+            'error' => 'AuthenticationRequired',
+            'message' => 'Invalid identifier or password',
+        ]);
+        $api = new BlueskyApi('identifier', 'wrongpassword', $httpComponent);
+
+        $api->createRecord($post);
+    }
+
     public function testCreateRecord(): void
     {
         $post = Post::create('Test for a post');