Update README.md

shahmal1yev · Sep 18, 2024 · cdbe66a · cdbe66a
1 parent ce03d69
commit cdbe66a
Show file tree

Hide file tree

Showing 5 changed files with 111 additions and 120 deletions.
diff --git a/README.md b/README.md
@@ -1,166 +1,157 @@
-# BlueskySDK
+<p align="center">
+  <img src="art/logo-small.webp" alt="Logo" />
+</p>
+
+# BlueSky SDK
+
+![GitHub tag (latest by date)](https://img.shields.io/github/v/tag/shahmal1yev/blueskysdk?label=latest&style=flat)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
+![GitHub last commit](https://img.shields.io/github/last-commit/shahmal1yev/blueskysdk)
+![GitHub issues](https://img.shields.io/github/issues/shahmal1yev/blueskysdk)
+![GitHub stars](https://img.shields.io/github/stars/shahmal1yev/blueskysdk)
+![GitHub forks](https://img.shields.io/github/forks/shahmal1yev/blueskysdk)
+![GitHub contributors](https://img.shields.io/github/contributors/shahmal1yev/blueskysdk)
 
 ## Project Description
 
-BlueskySDK is a PHP library used to interact with the Bluesky API. This library allows you to perform file uploads, create records, and other operations using the Bluesky API.
+BlueSky SDK is a PHP library used for interacting with the [BlueSky API](https://docs.bsky.app/docs/get-started). This library allows you to perform various
+operations using the BlueSky API.
 
 ## Requirements
 
-- PHP 5.6 or newer
-- Composer
+- **PHP**: 7.4 or newer
+- **Composer**: [Dependency management tool](https://getcomposer.org/) for PHP
 
 ## Installation
 
-```shell
+To install BlueSky SDK via Composer, use the following command:
+
+```bash
 composer require shahmal1yev/blueskysdk
 ```
 
 ## Usage
 
-After including the library in your project, you can refer to the following examples:
+Once installed, you can start using the SDK to interact with the BlueSky API. Below are examples of how to 
+authenticate and perform various operations using the library.
 
+### Authentication and Basic Usage
 
-### Get Profile
+First, instantiate the `Client` class and authenticate using your BlueSky credentials:
 
 ```php
-use Atproto\Clients\BlueskyClient;
-use Atproto\API\App\Bsky\Actor\GetProfile;
-use Atproto\Resources\App\Bsky\Actor\GetProfileResource;
-use Atproto\Resources\Assets\LabelsAsset;
-use Atproto\Resources\Assets\LabelAsset;
-use Atproto\Resources\Assets\FollowersAsset;
-use Atproto\Resources\Assets\FollowerAsset;
+use Atproto\Client;
+use Atproto\Resources\Com\Atproto\Server\CreateSessionResource;
 
-$client = new BlueskyClient(new GetProfile());
+$client = new Client();
 
-$client->authenticate([
-    'identifier' => 'user@example.com',
-    'password' => 'password'
-]);
+// Authenticate using your identifier (e.g., email) and password
+$client->authenticate($identifier, $password);
 
-/** @var GetProfileResource $user */
-$user = $client->send();
-
-/** @var Carbon\Carbon $created */
-$created = $user->createdAt();
+// Once authenticated, you can retrieve the user's session resource
+/** @var CreateSessionResource $session */
+$session = $client->authenticated();
+```
 
-/** @var LabelsAsset<LabelAsset> $labels */
-$labels = $user->labels();
+### Making Requests
 
-/** @var FollowersAsset $knownFollowers */
-$knownFollowers = $user->viewer()
-                    ->knownFollowers()
-                    ->followers();
+BlueSky SDK provides a fluent interface to construct API requests. Use chained method calls to navigate through the 
+API lexicons and forge the request:
 
-foreach($knownFollowers as $follower) {
-    /** @var FollowerAsset $follower */
-
-    $name = $follower->displayName();
-    $createdAt = $follower->createdAt()->format(DATE_ATOM);
-
-    echo "$name's account created at $createdAt";
-}
+```php
+use Atproto\Contracts\ResourceContract;
+
+// Example: Fetching a profile
+$profile = $client->app()
+                  ->bsky()
+                  ->actor()
+                  ->getProfile()
+                  ->forge()
+                  ->actor('some-actor-handle') // Specify the actor handle
+                  ->send();
 ```
 
-### File Upload
+### Handling Responses
+
+BlueSky SDK supports both Resource and Castable interfaces, providing flexibility in handling API responses and 
+enabling smooth data manipulation and casting for a more streamlined development experience.
+
+Responses are returned as resource instances that implement the `ResourceContract`. These resources provide methods 
+for accessing data returned by the API.
 
 ```php
-use Atproto\API\Com\Atrproto\Repo\UploadBlobRequest;
-use Atproto\Clients\BlueskyClient;
-use Atproto\Auth\Strategies\PasswordAuthentication;
+// Retrieve properties from the profile
+/** @var string $displayName */
+$displayName = $profile->displayName();
 
-$client = new BlueskyClient(new UploadBlobRequest);
+/** @var Carbon\Carbon $createdAt */
+$createdAt = $profile->createdAt();
+```
 
-$client->setStrategy(new PasswordAuthentication)
-    ->authenticate([
-        'identifier' => 'user@example.com',
-        'password' => 'password'
-    ]);
+### Working with Assets and Relationships
 
-$client->getRequest()
-    ->setBlob('/var/www/blueskysdk/assets/file.png');
+BlueSky SDK allows you to access complex assets like followers and labels directly through the resource instances.
 
-$response = $client->execute();
+```php
+use Atproto\Resources\Assets\FollowersAsset;
+use Atproto\Resources\Assets\FollowerAsset;
+
+// Fetch the user's followers
+/** @var FollowersAsset<FollowerAsset> $followers */
+$followers = $profile->viewer()
+                     ->knownFollowers()
+                     ->followers();
 
-echo "Blob uploaded successfully. CID: {$response->cid}";
+foreach ($followers as $follower) {
+    /** @var FollowerAsset $follower */
+    echo $follower->displayName() . " - Created at: " . $follower->createdAt()->format(DATE_ATOM) . "\n";
+}
 ```
 
-### Record Creation
+### Example: Fetching Profile Information
+
+Here is a more complete example of fetching and displaying profile information, including created dates and labels:
+
 ```php
-use Atproto\API\Com\Atrproto\Repo\CreateRecordRequest;
 use Atproto\Clients\BlueskyClient;
-use Atproto\Auth\Strategies\PasswordAuthentication;
+use Atproto\API\App\Bsky\Actor\GetProfile;
+use Atproto\Resources\App\Bsky\Actor\GetProfileResource;
 
-$client = new BlueskyClient(new CreateRecordRequest);
+$client = new BlueskyClient(new GetProfile());
+
+$client->authenticate([
+    'identifier' => 'user@example.com',
+    'password' => 'password'
+]);
 
-$client->setStrategy(new PasswordAuthentication)
-    ->authenticate([
-        'identifier' => 'user@example.com',
-        'password' => 'password'
-    ]);
-
-$record = new \Atproto\Builders\Bluesky\RecordBuilder();
+/** @var GetProfileResource $user */
+$user = $client->send();
 
-$record->addText("Hello World!")
-    ->addText("")
-    ->addText("I was sent via BlueskySDK: https://github.com/shahmal1yev/blueskysdk")
-    ->addCreatedAt(date_format(date_create_from_format("d/m/Y", "08/11/2020"), "c"))
-    ->addType();
+// Output profile details
+echo "Display Name: " . $user->displayName() . "\n";
+echo "Created At: " . $user->createdAt()->toDateTimeString() . "\n";
+echo "Labels: " . implode(', ', $user->labels()->pluck('name')->toArray()) . "\n";
 
-$client->getRequest()
-    ->setRecord($record);
+// Accessing and iterating over followers
+$followers = $user->viewer()->knownFollowers()->followers();
 
-echo "Record created successfully. URI: {$response->uri}";
+foreach ($followers as $follower) {
+    echo $follower->displayName() . " followed on " . $follower->createdAt()->format(DATE_ATOM) . "\n";
+}
 ```
-### Create Record (with blob)
 
-```php
-use Atproto\API\Com\Atrproto\Repo\UploadBlobRequest;
-use Atproto\Auth\Strategies\PasswordAuthentication;
-use Atproto\Clients\BlueskyClient;
-use Atproto\API\Com\Atrproto\Repo\CreateRecordRequest;
-
-$client = new BlueskyClient(new UploadBlobRequest);
-
-$client->setStrategy(new PasswordAuthentication)
-    ->authenticate([
-        'identifier' => 'user@example.com',
-        'password' => 'password'
-    ]);
-
-$client->getRequest()
-    ->setBlob('/var/www/blueskysdk/assets/file.png')
-    ->setHeaders([
-        'Content-Type' => $client->getRequest()
-            ->getBlob()
-            ->getMimeType()
-    ]);
-
-$image = $client->execute();
-
-$client->setRequest(new CreateRecordRequest);
-
-$record = (new \Atproto\Builders\Bluesky\RecordBuilder)
-    ->addText("Hello World!")
-    ->addText("")
-    ->addText("I was sent from 'test BlueskyClient execute method with both UploadBlob and CreateRecord'")
-    ->addText("")
-    ->addText("Here are the pictures: ")
-    ->addImage($image->blob, "Image 1: Alt text")
-    ->addImage($image->blob, "Image 2: Alt text")
-    ->addType()
-    ->addCreatedAt();
-
-$client->getRequest()
-    ->setRecord($record);
-
-$response = $client->execute();
-```
+### Extending the SDK
+
+BlueSky SDK is built with extensibility in mind. You can add custom functionality by extending existing classes and 
+creating your own request and resource types. Follow the structure used in the SDK to maintain consistency.
 
 ## Contribution
-- If you find any bug or issue, please open an issue.
-- If you want to contribute to the code, feel free to submit a pull request.
+
+We welcome contributions from the community! If you find any bugs or would like to add new features, feel free to:
+
+- **Open an issue**: Report bugs, request features, or suggest improvements.
+- **Submit a pull request**: Contributions to the codebase are welcome. Please follow best practices and ensure that your code adheres to the existing architecture and coding standards.
 
 ## License
 
-This project is licensed under the MIT License. For more information, see the LICENSE file.
+BlueSky SDK is licensed under the MIT License. See the LICENSE file for full details.
diff --git a/assets/file.png → art/file.png b/assets/file.png → art/file.png
diff --git a/art/logo-small.webp b/art/logo-small.webp
diff --git a/art/logo.webp b/art/logo.webp
diff --git a/tests/Feature/BlueskyClientTest.php b/tests/Feature/BlueskyClientTest.php
@@ -137,7 +137,7 @@ public function testExecuteWithUploadBlob()
                 'password' => $_ENV["BLUESKY_PASSWORD"]
             ]);
 
-        $client->getRequest()->setBlob('assets/file.png');
+        $client->getRequest()->setBlob('art/file.png');
 
         $response = $client->execute();
 
@@ -206,7 +206,7 @@ public function testSendWithGetProfile()
      */
     public function testSendWithRequestWhichHasNotResourceSupport()
     {
-        $request = (new UploadBlob())->setBlob('assets/file.png');
+        $request = (new UploadBlob())->setBlob('art/file.png');
 
         $client = new BlueskyClient($request);
 
@@ -233,7 +233,7 @@ public function testExecuteWithUploadBlobAndCreateRecord()
             ]);
 
         $client->getRequest()
-            ->setBlob('assets/file.png')
+            ->setBlob('art/file.png')
             ->setHeaders([
                 'Content-Type' => $client->getRequest()
                     ->getBlob()