Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion KNOWLEDGE_BASE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
5 changes: 4 additions & 1 deletion app/Http/Controllers/Api/UserController.php
Original file line number Diff line number Diff line change
Expand Up @@ -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
{
Expand All @@ -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),
]);
}
}
28 changes: 28 additions & 0 deletions app/Queries/BioProfilesQuery.php
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@

namespace App\Queries;

use App\Enums\ProfileType;
use App\Models\Profile;
use App\Models\User;
use App\Services\Mentions;
Expand Down Expand Up @@ -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<string, 'user'|'organization'|'unclaimed'>
*/
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();
}
}
29 changes: 26 additions & 3 deletions tests/Feature/Controllers/Api/UserControllerTest.php
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -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',
Expand All @@ -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 {
Expand Down Expand Up @@ -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();
});
Expand Down Expand Up @@ -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)
Expand All @@ -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 {
Expand Down
22 changes: 22 additions & 0 deletions tests/Unit/Queries/BioProfilesQueryTest.php
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -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([]);
});