diff --git a/KNOWLEDGE_BASE.md b/KNOWLEDGE_BASE.md index a34915941..cd118a103 100644 --- a/KNOWLEDGE_BASE.md +++ b/KNOWLEDGE_BASE.md @@ -573,7 +573,7 @@ Sources: [GitHub action](.github/actions/commit/action.yml). ### Public read API and Atom feeds -The read-only JSON API at `/api/v1` requires no authentication or token, except for who follows whom. Read a public profile at `/api/v1/users/{handle}`, that user's commits at `/api/v1/users/{handle}/commits`, or one commit at `/api/v1/commits/{commit}`. `/api/v1/users/{handle}/followers` and `/following` list people the way the profile's people lists do, newest follow first, with each person's lane and whether you follow each other, and `/api/v1/users/{handle}/following/organizations` lists the organizations they follow the same way, with whether you follow each one; like on the web, they are for members only and need a [signed request](#signed-api-and-devices). Add `?replies=1` to the user-commits endpoint to read their replies instead of top-level commits. Lists use cursor pagination: 20 commits, or 30 people or organizations, per page. Only public approved, non-deleted content is returned, not private profile data such as email. Unsigned requests are limited to **60 requests per minute per IP** and cannot create posts, follow, or star; terminal posting and the [signed API](#signed-api-and-devices) are separate signed interfaces. +The read-only JSON API at `/api/v1` requires no authentication or token, except for who follows whom. Read a public profile at `/api/v1/users/{handle}`, that user's commits at `/api/v1/users/{handle}/commits`, or one commit at `/api/v1/commits/{commit}`. A profile also says which accounts tagged in its bio and company have a page here, and whether each is a user, an organization or an unclaimed developer, so an app can open the right page. `/api/v1/users/{handle}/followers` and `/following` list people the way the profile's people lists do, newest follow first, with each person's lane and whether you follow each other, and `/api/v1/users/{handle}/following/organizations` lists the organizations they follow the same way, with whether you follow each one; like on the web, they are for members only and need a [signed request](#signed-api-and-devices). Add `?replies=1` to the user-commits endpoint to read their replies instead of top-level commits. Lists use cursor pagination: 20 commits, or 30 people or organizations, per page. Only public approved, non-deleted content is returned, not private profile data such as email. Unsigned requests are limited to **60 requests per minute per IP** and cannot create posts, follow, or star; terminal posting and the [signed API](#signed-api-and-devices) are separate signed interfaces. Subscribe in a feed reader to `/@{handle}/feed.atom` for a profile's latest **50 approved top-level commits**, including image enclosures. Feeds are public and can be cached for five minutes. diff --git a/app/Http/Controllers/Api/UserController.php b/app/Http/Controllers/Api/UserController.php index 1b1725481..9c75e47de 100644 --- a/app/Http/Controllers/Api/UserController.php +++ b/app/Http/Controllers/Api/UserController.php @@ -23,7 +23,8 @@ * A signed request gets the profile as the web shows it to that user, with whether they mute it, its achievements * and Unix rank, and how many pastéis it was given, which the app only shows in pastéis mode, as the web does. The * pinned commit is left out of the commits list, so it comes with the profile, as on the web. Anyone gets which - * handles the bio mentions have a page on /dev/null, by lowercase handle, so only those link to one. + * handles the bio and company mention have a page on /dev/null, by lowercase handle, so only those link to one, and whether each + * is a user, an organization or an unclaimed developer, so the app opens the right screen. */ public function show(ShowApiUserRequest $request, #[CurrentUser] ?User $currentUser, User $user, UserActivityQuery $activity, UserStreakQuery $streaks, UserAchievementsQuery $achievements, PinnedCommitQuery $pinned, ReplyPreviewsQuery $replyPreviews, BioProfilesQuery $bioProfiles): UserResource { @@ -44,11 +45,13 @@ public function show(ShowApiUserRequest $request, #[CurrentUser] ?User $currentU 'achievements' => $achievements->get($user, $currentUser, $userStreaks), 'pinned_commit' => $pinnedCommit instanceof Commit ? CommitResource::make($pinnedCommit) : null, 'bio_profiles' => (object) $bioProfiles->get($user), + 'bio_profile_types' => (object) $bioProfiles->types($user), ]); } return UserResource::make($user->loadPublicCounts())->additional([ 'bio_profiles' => (object) $bioProfiles->get($user), + 'bio_profile_types' => (object) $bioProfiles->types($user), ]); } } diff --git a/app/Queries/BioProfilesQuery.php b/app/Queries/BioProfilesQuery.php index 353c04e21..759272653 100644 --- a/app/Queries/BioProfilesQuery.php +++ b/app/Queries/BioProfilesQuery.php @@ -4,6 +4,7 @@ namespace App\Queries; +use App\Enums\ProfileType; use App\Models\Profile; use App\Models\User; use App\Services\Mentions; @@ -36,4 +37,31 @@ public function get(User $user): array ->mapWithKeys(fn (Profile $profile): array => [Str::lower($profile->handle) => $profile->handle]) ->all(); } + + /** + * What each of those profiles opens as, by lowercase handle, the way "/@{handle}" decides: a user's profile when a + * user has the handle, an organization's page, or an unclaimed developer's page. + * + * @return array + */ + public function types(User $user): array + { + $handles = $this->mentions->handles("{$user->bio}\n{$user->company}"); + + if ($handles === []) { + return []; + } + + return Profile::query() + ->select(['id', 'handle', 'type']) + ->whereIn('handle', $handles) + ->withExists('user') + ->get() + ->mapWithKeys(fn (Profile $profile): array => [Str::lower($profile->handle) => match (true) { + (bool) $profile->getAttribute('user_exists') => 'user', + $profile->type === ProfileType::Organization => 'organization', + default => 'unclaimed', + }]) + ->all(); + } } diff --git a/tests/Feature/Controllers/Api/UserControllerTest.php b/tests/Feature/Controllers/Api/UserControllerTest.php index f15b3390a..15c357519 100644 --- a/tests/Feature/Controllers/Api/UserControllerTest.php +++ b/tests/Feature/Controllers/Api/UserControllerTest.php @@ -5,6 +5,8 @@ use App\Enums\LivePlatform; use App\Models\Commit; use App\Models\CommitImage; +use App\Models\Organization; +use App\Models\Profile; use App\Models\User; use App\Queries\UserAchievementsQuery; use App\Queries\UserActivityQuery; @@ -31,7 +33,7 @@ $response = $this->getJson(route('api-user.show', $user)); $response->assertOk() - ->assertExactJson(['bio_profiles' => [], 'data' => [ + ->assertExactJson(['bio_profiles' => [], 'bio_profile_types' => [], 'data' => [ 'id' => $user->id, 'handle' => 'octocat', 'name' => 'The Octocat', @@ -50,7 +52,9 @@ 'following_count' => 1, ]]); - expect(json_decode($response->getContent(), flags: JSON_THROW_ON_ERROR)->bio_profiles)->toBeInstanceOf(stdClass::class); + expect(json_decode($response->getContent(), flags: JSON_THROW_ON_ERROR)) + ->bio_profiles->toBeInstanceOf(stdClass::class) + ->bio_profile_types->toBeInstanceOf(stdClass::class); }); it('never exposes hidden fields', function (): void { @@ -109,6 +113,22 @@ ->assertJsonPath('data.live', null); }); +it('says whether each profile the bio tags is a user, an organization or an unclaimed developer', function (): void { + Organization::factory()->create(['handle' => 'Laravel']); + User::factory()->create(['handle' => 'eveline24']); + Profile::factory()->create(['handle' => 'taylor']); + $user = User::factory()->create(['bio' => 'Thanks @Eveline24, @taylor and @nobody', 'company' => '@laravel']); + $keyPair = apiKeyPairFor(User::factory()->create()); + + $types = ['eveline24' => 'user', 'taylor' => 'unclaimed', 'laravel' => 'organization']; + + expect($this->getJson(route('api-user.show', $user))->assertOk()->json()) + ->bio_profiles->toEqual(['eveline24' => 'eveline24', 'taylor' => 'taylor', 'laravel' => 'Laravel']) + ->bio_profile_types->toEqual($types); + + expect(signedApiRequest($keyPair, 'GET', route('api-user.show', $user))->assertOk()->json('bio_profile_types'))->toEqual($types); +}); + it('returns not found for unknown handles', function (): void { $this->getJson('/api/v1/users/missing')->assertNotFound(); }); @@ -168,6 +188,7 @@ 'achievements' => resolve(UserAchievementsQuery::class)->get($user, $viewer), 'pinned_commit' => null, 'bio_profiles' => [], + 'bio_profile_types' => [], ]) ->assertJsonPath('achievements.rank', 'daemon') ->assertJsonPath('achievements.level', 2) @@ -177,7 +198,9 @@ ->assertJsonPath('activity.buckets.3', ['date' => '2026-10-12', 'count' => 1]) ->assertJsonPath('activity.buckets.6', ['date' => '2026-10-15', 'count' => 2]); - expect(json_decode($response->getContent(), flags: JSON_THROW_ON_ERROR)->bio_profiles)->toBeInstanceOf(stdClass::class); + expect(json_decode($response->getContent(), flags: JSON_THROW_ON_ERROR)) + ->bio_profiles->toBeInstanceOf(stdClass::class) + ->bio_profile_types->toBeInstanceOf(stdClass::class); }); it('counts the pending commits of a signed-in user on their own profile', function (): void { diff --git a/tests/Unit/Queries/BioProfilesQueryTest.php b/tests/Unit/Queries/BioProfilesQueryTest.php index 08d326291..03db56d0c 100644 --- a/tests/Unit/Queries/BioProfilesQueryTest.php +++ b/tests/Unit/Queries/BioProfilesQueryTest.php @@ -3,6 +3,7 @@ declare(strict_types=1); use App\Models\Organization; +use App\Models\Profile; use App\Models\User; use App\Queries\BioProfilesQuery; use Illuminate\Support\Facades\DB; @@ -23,3 +24,24 @@ expect(resolve(BioProfilesQuery::class)->get($user))->toBe([]); expect(DB::getQueryLog())->toBe([]); }); + +it('says what each profile the bio and company mention opens as, in one query', function (): void { + Organization::factory()->create(['handle' => 'Laravel']); + User::factory()->create(['handle' => 'taylorotwell']); + Profile::factory()->create(['handle' => 'Unclaimed']); + $user = User::factory()->create(['bio' => 'Thanks @TaylorOtwell, @unclaimed, not `@laravel` in code, and @nobody', 'company' => '@laravel']); + + DB::enableQueryLog(); + + expect(resolve(BioProfilesQuery::class)->types($user))->toEqual(['laravel' => 'organization', 'taylorotwell' => 'user', 'unclaimed' => 'unclaimed']); + expect(DB::getQueryLog())->toHaveCount(1); +}); + +it('asks nothing for the types of a bio that mentions no one', function (): void { + $user = User::factory()->create(['bio' => 'Building things', 'company' => null]); + + DB::enableQueryLog(); + + expect(resolve(BioProfilesQuery::class)->types($user))->toBe([]); + expect(DB::getQueryLog())->toBe([]); +});