From 68ecdab2e7dc4041092c88c9a6a2e0f2d9df7950 Mon Sep 17 00:00:00 2001 From: Shane Smith Date: Fri, 20 Nov 2026 02:39:23 +1030 Subject: [PATCH] feat: let API clients read and clear a guild's missed commits The web lists joined guilds on the left with the commits missed since the last visit, and opening a board clears that count. API clients had neither, so the apps couldn't show which guilds have something new. - GET api/v1/me/guilds lists the joined, unmuted guilds as the web's left navigation does, with missed_commits, read_from and html_url. - PUT api/v1/guilds/{handle}/read marks a guild read through the web's UpdateGuildRead, so the user's other clients update too. - The web and API share one 120-a-minute guild-reads limit. --- KNOWLEDGE_BASE.md | 1 + .../Controllers/Api/GuildReadController.php | 26 +++++++ .../Controllers/Api/JoinedGuildController.php | 27 ++++++++ .../Requests/ListApiJoinedGuildsRequest.php | 24 +++++++ .../Requests/UpdateApiGuildReadRequest.php | 24 +++++++ app/Queries/JoinedGuildsQuery.php | 15 ++-- routes/api.php | 8 +++ routes/web.php | 2 +- .../Api/GuildReadControllerTest.php | 69 +++++++++++++++++++ .../Api/JoinedGuildControllerTest.php | 69 +++++++++++++++++++ 10 files changed, 259 insertions(+), 6 deletions(-) create mode 100644 app/Http/Controllers/Api/GuildReadController.php create mode 100644 app/Http/Controllers/Api/JoinedGuildController.php create mode 100644 app/Http/Requests/ListApiJoinedGuildsRequest.php create mode 100644 app/Http/Requests/UpdateApiGuildReadRequest.php create mode 100644 tests/Feature/Controllers/Api/GuildReadControllerTest.php create mode 100644 tests/Feature/Controllers/Api/JoinedGuildControllerTest.php diff --git a/KNOWLEDGE_BASE.md b/KNOWLEDGE_BASE.md index 1073cf7f3..943dfda4f 100644 --- a/KNOWLEDGE_BASE.md +++ b/KNOWLEDGE_BASE.md @@ -596,6 +596,7 @@ A signed request sees what the web shows you, such as your own pending commits a - read the hot topics, and each one's commits from the past week with its recap; - list guilds as the Guilds page does, 24 a page, searched by name, handle or description, with whether you joined or muted each one and whether it is paused, while guilds are available to you; - read a guild's board as its page does, 30 threads a page with reply previews, with the guild, its pinned commit and whether you moderate it, while guilds are available to you. The pinned commit also keeps its place in the list, so an app that shows it apart skips it there by its id; +- list the guilds you joined as the left navigation does, with the commits you missed in each and when that count starts, and mark a guild read as opening its board does, sharing the web's limit of 120 a minute; - star or unstar, and list who starred your own commit, newest first, 20 a page; - create polls on commits that are neither replies nor quotes, and vote on polls; - change Remotes settings, read and send messages with images, link cards, and voice notes in conversations and orgs, mark them pulled, react to messages and list your reactions, pin and unpin org messages as a maintainer, find people, and start orgs; diff --git a/app/Http/Controllers/Api/GuildReadController.php b/app/Http/Controllers/Api/GuildReadController.php new file mode 100644 index 000000000..4037876a7 --- /dev/null +++ b/app/Http/Controllers/Api/GuildReadController.php @@ -0,0 +1,26 @@ +handle($user, $guild); + + return response()->noContent(); + } +} diff --git a/app/Http/Controllers/Api/JoinedGuildController.php b/app/Http/Controllers/Api/JoinedGuildController.php new file mode 100644 index 000000000..00b3c8d9d --- /dev/null +++ b/app/Http/Controllers/Api/JoinedGuildController.php @@ -0,0 +1,27 @@ +json(['data' => array_map(fn (array $guild): array => [ + ...$guild, + 'html_url' => route('guild.show', $guild['handle']), + ], $guilds->get($user, apiIcons: true))]); + } +} diff --git a/app/Http/Requests/ListApiJoinedGuildsRequest.php b/app/Http/Requests/ListApiJoinedGuildsRequest.php new file mode 100644 index 000000000..40d092544 --- /dev/null +++ b/app/Http/Requests/ListApiJoinedGuildsRequest.php @@ -0,0 +1,24 @@ +available(Feature::Guilds, $this->user()) ? Response::allow() : Response::denyAsNotFound(); + } + + /** @return array{} */ + public function rules(): array + { + return []; + } +} diff --git a/app/Http/Requests/UpdateApiGuildReadRequest.php b/app/Http/Requests/UpdateApiGuildReadRequest.php new file mode 100644 index 000000000..331c49c5d --- /dev/null +++ b/app/Http/Requests/UpdateApiGuildReadRequest.php @@ -0,0 +1,24 @@ +available(Feature::Guilds, $this->user()) ? Response::allow() : Response::denyAsNotFound(); + } + + /** @return array{} */ + public function rules(): array + { + return []; + } +} diff --git a/app/Queries/JoinedGuildsQuery.php b/app/Queries/JoinedGuildsQuery.php index fda59ae0d..cd40b5bc3 100644 --- a/app/Queries/JoinedGuildsQuery.php +++ b/app/Queries/JoinedGuildsQuery.php @@ -19,7 +19,7 @@ use Illuminate\Support\Facades\DB; /** - * @phpstan-type JoinedGuild array{handle: string, name: string, emoji: string, icon_url: string|null, missed_commits: int} + * @phpstan-type JoinedGuild array{handle: string, name: string, emoji: string, icon_url: string|null, missed_commits: int, read_from: string} */ final readonly class JoinedGuildsQuery { @@ -30,8 +30,12 @@ public function __construct(private Features $features, private Hashtags $hashta // } - /** @return list */ - public function get(User $user): array + /** + * With apiIcons, icon_url is the signed URL API clients load the icon from, as they send no web session. + * + * @return list + */ + public function get(User $user, bool $apiIcons = false): array { if (! $this->features->available(Feature::Guilds, $user)) { return []; @@ -52,16 +56,17 @@ public function get(User $user): array ]); return array_values($guilds - ->map(function (Guild $guild) use ($commits, $readFrom): array { + ->map(function (Guild $guild) use ($commits, $readFrom, $user, $apiIcons): array { $guildReadFrom = CarbonImmutable::parse($readFrom[$guild->id]); return [ 'handle' => $guild->handle, 'name' => $guild->name, 'emoji' => $guild->emoji, - 'icon_url' => $guild->iconUrl(), + 'icon_url' => $apiIcons ? $guild->apiIconUrl($user) : $guild->iconUrl(), 'missed_commits' => $commits->filter(fn (array $commit): bool => $this->isPostedIn($guild, $commit) && $commit['created_at']->greaterThan($guildReadFrom))->count(), + 'read_from' => $guildReadFrom->toIso8601ZuluString(), ]; }) ->sortBy([ diff --git a/routes/api.php b/routes/api.php index 979b5dba8..11b00c444 100644 --- a/routes/api.php +++ b/routes/api.php @@ -33,9 +33,11 @@ use App\Http\Controllers\Api\DevicePushTokenController; use App\Http\Controllers\Api\GuildController; use App\Http\Controllers\Api\GuildIconController; +use App\Http\Controllers\Api\GuildReadController; use App\Http\Controllers\Api\HeadlineController; use App\Http\Controllers\Api\IssueController; use App\Http\Controllers\Api\IssueSuggestionController; +use App\Http\Controllers\Api\JoinedGuildController; use App\Http\Controllers\Api\LiveFollowingController; use App\Http\Controllers\Api\LogController; use App\Http\Controllers\Api\MentionSuggestionController; @@ -245,6 +247,12 @@ Route::get('guilds', [GuildController::class, 'index'])->name('api-guild.index'); Route::get('guilds/{guild:handle}', [GuildController::class, 'show'])->name('api-guild.show'); + // Joined guilds: the ones the web's left navigation lists, with the number of commits missed since the last visit... + Route::get('me/guilds', [JoinedGuildController::class, 'index'])->name('api-joined-guild.index'); + Route::put('guilds/{guild:handle}/read', [GuildReadController::class, 'update']) + ->middleware('throttle:120,1,guild-reads:') + ->name('api-guild-read.update'); + // Composer suggestions: people to mention and /dev/null issues to reference, as the web's composer suggests them... Route::get('search/mentions', [MentionSuggestionController::class, 'index']) ->middleware('throttle:people') diff --git a/routes/web.php b/routes/web.php index 3338fbb40..34103d0fb 100644 --- a/routes/web.php +++ b/routes/web.php @@ -383,7 +383,7 @@ ->whereUuid('commit')->withTrashed()->middleware('throttle:pins')->name('guild-commit-pin.update'); Route::put('guild-memberships/{guild}', [GuildMembershipController::class, 'update'])->whereUuid('guild')->middleware('throttle:follows')->name('guild-membership.update'); Route::put('guild-mutes/{guild}', [GuildMuteController::class, 'update'])->whereUuid('guild')->middleware('throttle:follows')->name('guild-mute.update'); - Route::put('guild-reads/{guild}', [GuildReadController::class, 'update'])->whereUuid('guild')->middleware('throttle:120,1')->name('guild-read.update'); + Route::put('guild-reads/{guild}', [GuildReadController::class, 'update'])->whereUuid('guild')->middleware('throttle:120,1,guild-reads:')->name('guild-read.update'); Route::post('guild-reports/{guild}', [GuildReportController::class, 'store'])->whereUuid('guild')->middleware('throttle:10,1')->name('guild-report.store'); }); diff --git a/tests/Feature/Controllers/Api/GuildReadControllerTest.php b/tests/Feature/Controllers/Api/GuildReadControllerTest.php new file mode 100644 index 000000000..aa822bf82 --- /dev/null +++ b/tests/Feature/Controllers/Api/GuildReadControllerTest.php @@ -0,0 +1,69 @@ +update(Feature::Guilds, true, adminOnly: false); + $this->travelTo('2026-11-18 12:00:00'); + + $this->user = User::factory()->create(); + $this->keyPair = apiKeyPairFor($this->user); + $this->guild = Guild::factory()->create(['handle' => 'rust']); +}); + +it('marks a joined guild read, clears its missed commits and tells the other clients of the user', function (): void { + DB::table('guild_preferences')->insert(['user_id' => $this->user->id, 'guild_id' => $this->guild->id, 'joined_at' => '2026-11-01 00:00:00']); + Commit::factory()->for(User::factory())->create(['guild_id' => $this->guild->id, 'created_at' => '2026-11-18 11:00:00']); + + signedApiRequest($this->keyPair, 'GET', route('api-joined-guild.index'))->assertJsonPath('data.0.missed_commits', 1); + + Event::fake([UsersUpdated::class]); + + signedApiRequest($this->keyPair, 'PUT', route('api-guild-read.update', 'rust'))->assertNoContent(); + + expect(DB::table('guild_preferences')->where('user_id', $this->user->id)->value('read_at'))->toBe('2026-11-18 12:00:00'); + Event::assertDispatched(UsersUpdated::class, fn (UsersUpdated $event): bool => $event->update === UserUpdate::Guilds && $event->userIds === [$this->user->id]); + + signedApiRequest($this->keyPair, 'GET', route('api-joined-guild.index')) + ->assertJsonPath('data.0.missed_commits', 0) + ->assertJsonPath('data.0.read_from', '2026-11-18T12:00:00Z'); +}); + +it('writes nothing for a guild the user did not join', function (): void { + Event::fake([UsersUpdated::class]); + + signedApiRequest($this->keyPair, 'PUT', route('api-guild-read.update', 'rust'))->assertNoContent(); + + expect(DB::table('guild_preferences')->count())->toBe(0); + Event::assertNotDispatched(UsersUpdated::class); +}); + +it('hides the endpoint without the guilds feature, and for a missing guild', function (): void { + signedApiRequest($this->keyPair, 'PUT', route('api-guild-read.update', 'missing'))->assertNotFound(); + + resolve(Features::class)->update(Feature::Guilds, false, adminOnly: false); + + signedApiRequest($this->keyPair, 'PUT', route('api-guild-read.update', 'rust'))->assertNotFound(); +}); + +it('shares the 120 reads a minute with the web', function (): void { + foreach (range(1, 120) as $read) { + $this->actingAs($this->user)->put(route('guild-read.update', $this->guild->id))->assertRedirect(); + } + + signedApiRequest($this->keyPair, 'PUT', route('api-guild-read.update', 'rust'))->assertTooManyRequests(); +}); + +it('requires a signed request', function (): void { + $this->putJson(route('api-guild-read.update', 'rust'))->assertUnauthorized(); +}); diff --git a/tests/Feature/Controllers/Api/JoinedGuildControllerTest.php b/tests/Feature/Controllers/Api/JoinedGuildControllerTest.php new file mode 100644 index 000000000..467f7ec86 --- /dev/null +++ b/tests/Feature/Controllers/Api/JoinedGuildControllerTest.php @@ -0,0 +1,69 @@ +update(Feature::Guilds, true, adminOnly: false); + $this->travelTo('2026-11-18 12:00:00'); + + $this->user = User::factory()->create(); + $this->author = User::factory()->create(); + $this->keyPair = apiKeyPairFor($this->user); +}); + +function joinApiGuild(User $user, Guild $guild, string $joinedAt, ?string $readAt = null, ?string $mutedAt = null): void +{ + DB::table('guild_preferences')->insert(['user_id' => $user->id, 'guild_id' => $guild->id, 'joined_at' => $joinedAt, 'read_at' => $readAt, 'muted_at' => $mutedAt]); +} + +it('lists the joined guilds as the left navigation on the web does, the most missed commits first', function (): void { + $quiet = Guild::factory()->create(['handle' => 'aardvark', 'name' => 'Aardvark', 'emoji' => '🐜']); + $busy = Guild::factory()->create(['handle' => 'rust', 'name' => 'Rust', 'emoji' => '🦀', 'icon_path' => 'guild-icons/rust.webp']); + joinApiGuild($this->user, $quiet, '2026-11-01 00:00:00'); + joinApiGuild($this->user, $busy, '2026-11-01 00:00:00', '2026-11-18 10:00:00'); + joinApiGuild($this->user, Guild::factory()->create(['handle' => 'muted']), '2026-11-01 00:00:00', mutedAt: '2026-11-02 00:00:00'); + Guild::factory()->create(['handle' => 'unjoined']); + + Commit::factory()->for($this->author)->create(['guild_id' => $busy->id, 'created_at' => '2026-11-18 09:00:00']); + Commit::factory()->for($this->author)->count(2)->create(['guild_id' => $busy->id, 'created_at' => '2026-11-18 11:00:00']); + + signedApiRequest($this->keyPair, 'GET', route('api-joined-guild.index')) + ->assertOk() + ->assertJsonPath('data.*.handle', ['rust', 'aardvark']) + ->assertJsonPath('data.0', [ + 'handle' => 'rust', + 'name' => 'Rust', + 'emoji' => '🦀', + 'icon_url' => $busy->apiIconUrl($this->user), + 'missed_commits' => 2, + 'read_from' => '2026-11-18T10:00:00Z', + 'html_url' => route('guild.show', 'rust'), + ]) + ->assertJsonPath('data.1.missed_commits', 0) + ->assertJsonPath('data.1.read_from', '2026-11-01T00:00:00Z'); +}); + +it('lists nothing before the user joins a guild', function (): void { + Guild::factory()->create(); + + signedApiRequest($this->keyPair, 'GET', route('api-joined-guild.index')) + ->assertOk() + ->assertExactJson(['data' => []]); +}); + +it('hides the endpoint without the guilds feature', function (): void { + resolve(Features::class)->update(Feature::Guilds, false, adminOnly: false); + + signedApiRequest($this->keyPair, 'GET', route('api-joined-guild.index'))->assertNotFound(); +}); + +it('requires a signed request', function (): void { + $this->getJson(route('api-joined-guild.index'))->assertUnauthorized(); +});