Merge pull request #45 from shahmal1yev/bss-101

[BSS-101] Implement GetTimeline

Author: edevsh

.github/workflows/php.yml

@@ -2,9 +2,9 @@ name: PHP Workflow
 
 on:
   push:
-    branches: [ "main" ]
+    branches: [ "1.x" ]
   pull_request:
-    branches: [ "main" ]
+    branches: [ "1.x" ]
 
 permissions:
   contents: read

README.md

@@ -230,6 +230,54 @@ foreach ($response->posts() as $post) {
 }
 ```
 
+### GetTimeline
+
+Get a view of the requesting account's home timeline.
+
+```php
+$feed = $client->app()->bsky()->feed()->getTimeline()->forge()
+    ->limit(10)
+    ->send()
+    ->feed();
+
+foreach($feed as $entry) {
+    echo sprintf("Created by %s at %s" . PHP_EOL,
+        $entry->post()->author()->handle(),
+        $entry->post()->indexedAt()->format('d/m/Y H:i:s')
+    );
+}
+```
+
+### Call to non-implemented lexicons
+
+_Note that this is not recommended._
+
+It is possible to call non-implemented lexicons.
+
+```php
+use Atproto\Client;
+use Atproto\Lexicons\Request;
+use Atproto\Support\Arr;
+
+$client = new Client();
+$client->authenticate(getenv('BLUESKY_IDENTIFIER'), getenv('BLUESKY_PASSWORD'));
+
+$request = new Request();
+$request->origin('https://bsky.social/xrpc/app.bsky.feed.getTimeline')
+    ->method('GET')
+    ->headers([
+        'Accept' => 'application/json',
+        'Content-Type' => 'application/json',
+        'Authorization' => sprintf("Bearer %s", $client->authenticated()->accessJwt())
+    ]);
+
+/** @var array $response */
+$response = $request->send();
+
+echo Arr::get($response, 'cursor') . PHP_EOL;
+print_r($response);
+```
+
 ### Serialization
 
 Any lexicon can be serialized

src/Lexicons/App/Bsky/Feed/GetTimeline.php

@@ -0,0 +1,75 @@
+<?php
+
+namespace Atproto\Lexicons\App\Bsky\Feed;
+
+use Atproto\Client;
+use Atproto\Contracts\LexiconContract;
+use Atproto\Contracts\Lexicons\RequestContract;
+use Atproto\Contracts\Resources\ResponseContract;
+use Atproto\Exceptions\InvalidArgumentException;
+use Atproto\Lexicons\APIRequest;
+use Atproto\Lexicons\Traits\AuthenticatedEndpoint;
+use Atproto\Responses\App\Bsky\Feed\GetTimelineResponse;
+
+class GetTimeline extends APIRequest implements LexiconContract
+{
+    use AuthenticatedEndpoint;
+
+    public function __construct(Client $client)
+    {
+        parent::__construct($client);
+        $this->update($client);
+
+        $this->limit(50);
+    }
+
+    public function algorithm($algorithm = null)
+    {
+        if (is_null($algorithm)) {
+            return $this->queryParameter('algorithm');
+        }
+
+        $this->queryParameter('algorithm', $algorithm);
+
+        return $this;
+    }
+
+    /**
+     * @throws InvalidArgumentException
+     */
+    public function limit(int $limit = null)
+    {
+        if (is_null($limit)) {
+            return (int) $this->queryParameter('limit');
+        }
+
+        if ($limit < 1 || $limit > 100) {
+            throw new InvalidArgumentException("The limit must be between or equal to 1 and 100.");
+        }
+
+        $this->queryParameter('limit', $limit);
+
+        return $this;
+    }
+
+    public function cursor(string $cursor = null)
+    {
+        if (is_null($cursor)) {
+            return $this->queryParameter('cursor');
+        }
+
+        $this->queryParameter('cursor', $cursor);
+
+        return $this;
+    }
+
+    public function response(array $data): ResponseContract
+    {
+        return new GetTimelineResponse($data);
+    }
+
+    public function build(): RequestContract
+    {
+        return $this;
+    }
+}

src/Responses/App/Bsky/Feed/GetTimelineResponse.php

@@ -0,0 +1,22 @@
+<?php
+
+namespace Atproto\Responses\App\Bsky\Feed;
+
+use Atproto\Contracts\Resources\ResponseContract;
+use Atproto\Responses\BaseResponse;
+use Atproto\Responses\Objects\FeedObject;
+use Atproto\Traits\Castable;
+
+class GetTimelineResponse implements ResponseContract
+{
+    use BaseResponse;
+    use Castable;
+
+
+    protected function casts(): array
+    {
+        return [
+            'feed' => FeedObject::class
+        ];
+    }
+}

src/Responses/Objects/FeedItemObject.php

@@ -0,0 +1,26 @@
+<?php
+
+namespace Atproto\Responses\Objects;
+
+use Atproto\Contracts\Resources\ObjectContract;
+use Atproto\Traits\Castable;
+
+class FeedItemObject implements ObjectContract
+{
+    use BaseObject;
+    use Castable;
+
+    public function __construct(array $content)
+    {
+        $this->content = $content;
+    }
+
+    protected function casts(): array
+    {
+        return [
+            'post' => PostObject::class,
+            'reply' => ReplyObject::class,
+            'reason' => ReasonObject::class,
+        ];
+    }
+}

src/Responses/Objects/FeedObject.php

@@ -0,0 +1,26 @@
+<?php
+
+namespace Atproto\Responses\Objects;
+
+use Atproto\Contracts\Resources\ObjectContract;
+use Closure;
+use GenericCollection\Exceptions\InvalidArgumentException;
+use GenericCollection\GenericCollection;
+
+class FeedObject extends GenericCollection implements ObjectContract
+{
+    use CollectionObject;
+
+    /**
+     * @throws InvalidArgumentException
+     */
+    protected function item($data): ObjectContract
+    {
+        return new FeedItemObject($data);
+    }
+
+    protected function type(): Closure
+    {
+        return fn ($value): bool => $value instanceof FeedItemObject;
+    }
+}

src/Responses/Objects/ReasonObject.php

@@ -0,0 +1,21 @@
+<?php
+
+namespace Atproto\Responses\Objects;
+
+use Atproto\Contracts\Resources\ObjectContract;
+use Atproto\Traits\Castable;
+
+class ReasonObject implements ObjectContract
+{
+    use BaseObject;
+    use Castable;
+
+
+    protected function casts(): array
+    {
+        return [
+            'by' => AuthorObject::class,
+            'indexedAt' => DatetimeObject::class,
+        ];
+    }
+}

src/Responses/Objects/ReplyObject.php

@@ -0,0 +1,21 @@
+<?php
+
+namespace Atproto\Responses\Objects;
+
+use Atproto\Contracts\Resources\ObjectContract;
+use Atproto\Traits\Castable;
+
+class ReplyObject implements ObjectContract
+{
+    use BaseObject;
+    use Castable;
+
+    protected function casts(): array
+    {
+        return [
+            'grandparentAuthor' => AuthorObject::class,
+            'root' => PostObject::class,
+            'parent' => PostObject::class,
+        ];
+    }
+}

tests/Feature/Lexicons/App/Bsky/Feed/GetTimelineTest.php

@@ -0,0 +1,36 @@
+<?php
+
+namespace Tests\Feature\Lexicons\App\Bsky\Feed;
+
+use Atproto\Client;
+use Atproto\Responses\Objects\PostObject;
+use PHPUnit\Framework\TestCase;
+
+class GetTimelineTest extends TestCase
+{
+    private static Client $client;
+
+    public static function setUpBeforeClass(): void
+    {
+        static::$client = new Client();
+
+        static::$client->authenticate(getenv('BLUESKY_IDENTIFIER'), getenv('BLUESKY_PASSWORD'));
+    }
+
+    public function testGetTimeline(): void
+    {
+        $client = static::$client;
+
+        $getTimeline = $client->app()->bsky()->feed()->getTimeline()->forge()
+            ->limit(20);
+
+        $response = $getTimeline->send();
+
+        $this->assertNotEmpty($feed = $response->feed());
+
+        foreach($feed as $entry) {
+            $this->assertInstanceOf(PostObject::class, $post = $entry->post());
+            $this->assertSame($client->authenticated()->did(), $post->author()->did());
+        }
+    }
+}

tests/Unit/Lexicons/App/Bsky/Feed/GetTimelineTest.php

@@ -0,0 +1,70 @@
+<?php
+
+namespace Tests\Unit\Lexicons\App\Bsky\Feed;
+
+use Atproto\Client;
+use Atproto\Exceptions\InvalidArgumentException;
+use Atproto\Lexicons\App\Bsky\Feed\GetTimeline;
+use PHPUnit\Framework\TestCase;
+
+class GetTimelineTest extends TestCase
+{
+    private static GetTimeline $instance;
+
+    public static function setUpBeforeClass(): void
+    {
+        static::$instance = (new Client())->app()->bsky()->feed()->getTimeline()->forge();
+
+    }
+
+    public function testLimitCanChangeTheLimit(): void
+    {
+        $getTimeline = static::$instance;
+
+        $this->assertSame(50, $getTimeline->limit()); // default value
+
+        $getTimeline->limit($expected = 10);
+        $actual = $getTimeline->limit();
+
+        $this->assertSame($expected, $actual);
+    }
+
+    /** @dataProvider provideInvalidLimitCases */
+    public function testLimitThrowsExceptionWhenPassedInvalidArgument(int $invalidLimit): void
+    {
+        $this->expectException(InvalidArgumentException::class);
+        $this->expectExceptionMessage("The limit must be between or equal to 1 and 100.");
+
+        static::$instance->limit($invalidLimit);
+    }
+
+    public static function provideInvalidLimitCases(): array
+    {
+        return [
+            [0],
+            [-1],
+            [101],
+            [102]
+        ];
+    }
+
+    public function testCursorCanChangeTheCursor(): void
+    {
+        $this->assertNull(static::$instance->cursor()); // it is not available by default
+
+        static::$instance->cursor($expected = 'cursor value');
+        $actual = static::$instance->cursor();
+
+        $this->assertSame($expected, $actual);
+    }
+
+    public function testAlgorithmCanChangeTheAlgorithm(): void
+    {
+        $this->assertNull(static::$instance->algorithm());
+
+        static::$instance->algorithm($expected = 'algorithm value');
+        $actual = static::$instance->algorithm();
+
+        $this->assertSame($expected, $actual);
+    }
+}