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(); +});