diff --git a/.gitattributes b/.gitattributes index 78f41d7a80..4bc4c5dcd1 100644 --- a/.gitattributes +++ b/.gitattributes @@ -5,3 +5,5 @@ *.html diff=html *.md diff=markdown *.php diff=php + +resources/api/openapi.json linguist-generated=true diff --git a/DESIGN.md b/DESIGN.md index 1cb2aab6e5..25234bfa4f 100644 --- a/DESIGN.md +++ b/DESIGN.md @@ -300,6 +300,13 @@ Content sits on the Cool Shell in a grid of panels: Feed White, 8px, hairline-bo - **Status:** the console is the one place with status colors, `success` (lane-1's green) and `warning` (lane-5's ochre) beside Rm Red. They only ever mark state (healthy, watch, failing; event levels; better or worse than the period before) and always come with an icon, a sign or a word. They are not lanes and never mark a person. - **Charts:** drawn in SVG at their real size, one y-axis, hairline gridlines, mono 11px ticks. History is a 2px ink line; a forecast continues it as a dashed Muted Ink line over a 15% Muted Ink wash for its range, after a dashed Rail Gray "today" rule. Columns are at most 24px wide with a 2px surface gap between stacked segments. Hovering shows the inverted tooltip; every chart carries a screen-reader table. +### API Docs +The API docs use the Operations Console's shell (`ConsoleLayout`), for everyone, guests included: the wordmark with a bordered mono `api` chip, a sidebar grouping the guides under `guide`, the groups of the reference under `reference` and `openapi.json` under `elsewhere`, the theme switch and "Back to /dev/null" (without an avatar for a guest). The header names the section and says in one line what it holds; on the right a mono `v1` and a bordered Search control with its `⌘K` cap. + +- **Guides:** read like the site's other long pages, never a card per section: one Feed White sheet on the Cool Shell, as wide as the reference (1160px) so moving between them never changes the page's width, 8px and hairline-bordered, whose sections follow one another with a hairline between them, each under a Section heading that links to itself, a mono meta beside it when it has one. Prose at 15px, named values in a hairline list with mono keys like the settings, and code in the same code blocks as the reference and commits, highlighted on the server, its language above it. Signing a request shows its helpers under the same example tabs as the endpoints, in step with them. +- **Endpoints:** one panel each, folded to a row: a mono method chip, the mono path with its `{parameters}` muted, the truncated summary, and a bordered mono `public` or `signed` chip, the signed one with a lock. Being the console's, the docs use its status colors, by what a request does rather than by state: GET reads in `success`, POST, PUT and PATCH write in `warning`, DELETE in Rm Red, and a `signed` chip is `warning` while a `public` one stays muted. Each is a 10% wash with its text mixed 70% with the ink, so 12px stays readable; never blue, which only means "act here". Unfolded, it splits from lg into the endpoint on the left (parameters, body and answers, fields as rows with a mono name and type, a `required` chip tinted `warning` like a signed one, as something the caller has to give, enum values as mono chips, and the fields inside folded behind a Commit Blue "Show N fields") and its examples on the right, sticky, under page tabs with the sliding Commit Blue underline, in the commits' code blocks. An error every endpoint shares carries a Commit Blue "see Errors" link instead of its fields. A bordered mono `fields | schema` pair on each part, the picked one on the Blue Wash, swaps that part's body, responses or errors for its JSON schema in a code block, scrolling past 32rem, loaded only then: the fields stay in place until it arrives, dimmed under a mono "Loading the schema…" once it takes more than 300ms, and a failure lies over them, a one-line mono `fatal: no schema` with a Try again that keeps keyboard focus on the endpoint, while a screen reader hears once per endpoint that its schema could not be loaded. Picking a client picks it everywhere; a view is picked for its part alone. In the sticky examples column, only the example shown takes room, so the column follows the endpoint to its end. +- **Search:** the People Search palette's shell and keys, listing guides with their book icon and endpoints with their method chip, path and summary, the group in mono on the right; nothing found reads mono `fatal: nothing matches '…'`. + ### Error Pages 403, 404, 429, 500 (outside debug), and 503 render one standalone `error` page, with no app shell, for guests and signed-in users alike. A broken rail: the wordmark sits on a node in the viewer's lane (Rail Gray for guests) whose segment fades out before reaching a hollow, dangling node. Beside it, a mono git-style line (`fatal: path '/x' does not exist in 'HEAD'`), a Headline sentence saying what happened, one muted sentence saying what to do, and a single primary button ("Back to your log", "Go to the home page", or "Try again" during maintenance). A 419 is not a page: it redirects back with an error toast. diff --git a/KNOWLEDGE_BASE.md b/KNOWLEDGE_BASE.md index 32a4682a84..eae37548a1 100644 --- a/KNOWLEDGE_BASE.md +++ b/KNOWLEDGE_BASE.md @@ -574,7 +574,9 @@ The read-only JSON API at `/api/v1` requires no authentication or token, except 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. -Sources: [API routes](routes/api.php), [API controllers](app/Http/Controllers/Api), [feed generation](app/Actions/CreateUserFeed.php), [rate limits](app/Providers/AppServiceProvider.php). +The **API docs** at `/docs/api`, linked as **API** from the aside and the user menu, are readable by everyone. Five guides (Introduction, Authentication, Rate limits, Pagination, Errors) explain how the API works, including how to get a key approved and sign a request, with the rate limits and error codes read from the code, and the reference lists every endpoint but those only the apps need to work (signing in, the Mac app's update check, live updates, the web session, signed media URLs) by group, listed alphabetically (Commits, Headlines, Issues, Me, Notifications, Organizations, Remotes, Scheduled commits, Search, Users): its path and query parameters, the body it takes, what it answers and its errors apart, with the fields of a successful answer and of an error only it answers with, and how to call it with curl, Laravel's HTTP client or fetch. A signed example calls a signing helper that Authentication shows once for each client: `devnull_sign` for the shell, `devnullHeaders()` for Laravel and Node.js. An endpoint's body, responses and errors each read as fields or, on request for that part, as its JSON schema, each schema it refers to written once in its `$defs`; a schema is only loaded when shown. A request with images takes its fields as JSON, or as a signed multipart upload of that JSON beside the images. The client picked is shown on every endpoint, and kept in the browser. ⌘K, Ctrl+K or `/` searches the guides and endpoints. The reference is read from the API's OpenAPI 3.1 spec, generated from the code by Scramble in development and committed as `resources/api/openapi.json`; a test fails when the code and the committed spec disagree, and `composer generate:openapi` writes it again from a migrated database. Anyone can fetch it at `/api/v1/openapi.json`, unsigned, cached for an hour, to import it into Postman, Bruno or Insomnia, or generate a client. + +Sources: [API routes](routes/api.php), [API controllers](app/Http/Controllers/Api), [feed generation](app/Actions/CreateUserFeed.php), [rate limits](app/Providers/AppServiceProvider.php), [OpenAPI configuration](app/Providers/ApiDocumentationServiceProvider.php), [spec](resources/api/openapi.json), [docs page](app/Http/Controllers/ApiDocsController.php), [reference](app/Queries/ApiDocsQuery.php), [rate limits listed](app/Queries/ApiRateLimitsQuery.php), [error codes](app/Enums/ApiErrorCode.php), [examples](app/Services/ApiExamples.php), [guides](resources/js/pages/api-docs/guides). ### Signed API and devices diff --git a/app/Actions/CreateIssue.php b/app/Actions/CreateIssue.php index 21cb278e23..1bb9add020 100644 --- a/app/Actions/CreateIssue.php +++ b/app/Actions/CreateIssue.php @@ -16,6 +16,11 @@ final readonly class CreateIssue { + /** + * How many issues someone may open on GitHub a day, however they open them. + */ + public const int MAX_PER_DAY = 10; + public function __construct(private GitHubProvider $github) { // diff --git a/app/Enums/ApiDocsSection.php b/app/Enums/ApiDocsSection.php new file mode 100644 index 0000000000..32eb6322ea --- /dev/null +++ b/app/Enums/ApiDocsSection.php @@ -0,0 +1,99 @@ + + */ + public static function ordered(): array + { + return [...array_values(array_filter(self::cases(), fn (self $section): bool => $section->isGuide())), ...self::reference()]; + } + + /** + * The groups of the reference alphabetically, so a reader finds one by its name, wherever they are listed. + * + * @return list + */ + public static function reference(): array + { + $groups = array_values(array_filter(self::cases(), fn (self $section): bool => ! $section->isGuide())); + usort($groups, fn (self $a, self $b): int => strcmp($a->title(), $b->title())); + + return $groups; + } + + public function isGuide(): bool + { + return in_array($this, [self::Introduction, self::Authentication, self::RateLimits, self::Pagination, self::Errors], true); + } + + public function title(): string + { + return match ($this) { + self::RateLimits => 'Rate limits', + self::ScheduledCommits => 'Scheduled commits', + default => $this->name, + }; + } + + public function description(): string + { + return match ($this) { + self::Introduction => 'What the API is for, and where it lives', + self::Authentication => 'Reading as anyone, or signing requests as someone', + self::RateLimits => 'How many requests a minute, and what happens past that', + self::Pagination => 'Following a list from one page to the next', + self::Errors => 'What went wrong, and the code that says which error it is', + self::Users => 'Profiles, what they committed, and who follows whom', + self::Commits => 'Reading, writing, starring and replying to commits', + self::Organizations => 'GitHub organizations, their commits and their mentions', + self::Me => 'The signed-in user: their account, settings and devices', + self::Search => 'People, organizations and commits, by name or meaning', + self::ScheduledCommits => 'Commits waiting for their time to be posted', + self::Remotes => 'Conversations, orgs, messages and calls', + self::Notifications => 'What happened to the user, grouped as the inbox shows it', + self::Headlines => 'Hot topics: the headlines the aside shows, each with its recap', + self::Issues => 'Feature requests and bug reports, opened on GitHub', + }; + } + + /** + * @return array{slug: string, title: string, description: string, kind: 'guide'|'reference'} + */ + public function toArray(): array + { + return [ + 'slug' => $this->value, + 'title' => $this->title(), + 'description' => $this->description(), + 'kind' => $this->isGuide() ? 'guide' : 'reference', + ]; + } +} diff --git a/app/Enums/ApiErrorCode.php b/app/Enums/ApiErrorCode.php index 2cc4924d59..604519a9f3 100644 --- a/app/Enums/ApiErrorCode.php +++ b/app/Enums/ApiErrorCode.php @@ -39,4 +39,28 @@ public function status(): int self::GitHubSyncFailed => 503, }; } + + /** + * What the code means to someone building on the API, as the API docs list it. + */ + public function meaning(): string + { + return match ($this) { + self::InvalidSignature => 'The signature is missing, stale, already used, or does not match the request.', + self::DeviceNotApproved => 'The signature is right, but its key is not an approved device, or not any more.', + self::InvalidGrant => 'The sign-in code is unknown, expired or already used, was issued for another key, does not match the verifier, or its account was deleted since.', + self::UserBlocked => 'You blocked this person. The answer also has their profile, as user.', + self::UserUnavailable => 'This profile is not available to you.', + self::OwnCommit => 'You cannot report your own commit.', + self::CommitUnavailable => 'The commit you report does not exist, was deleted, is not published, or is not yours to see. Elsewhere, such a commit is a plain 404.', + self::PasteisExhausted => 'No pastéis left today.', + self::RateLimited => 'Too many requests. Wait the seconds Retry-After says.', + self::GitHubSyncFailed => 'GitHub did not answer. Try again in a minute.', + self::GitHubIssueRefused => 'GitHub did not create the issue, so trying again is safe.', + self::GitHubIssueUnanswered => 'GitHub did not answer, so the issue may exist: check the upstream issues before trying again.', + self::TimedOut => 'Moderators paused posting for this account for a while.', + self::Banned => 'The account is banned. All it can do is delete itself.', + self::CommitRulesRequired => 'The commit rules have to be accepted once, in the web composer.', + }; + } } diff --git a/app/Http/Controllers/Api/OpenApiController.php b/app/Http/Controllers/Api/OpenApiController.php new file mode 100644 index 0000000000..5b40c8d4fd --- /dev/null +++ b/app/Http/Controllers/Api/OpenApiController.php @@ -0,0 +1,20 @@ + 'application/json']); + } +} diff --git a/app/Http/Controllers/ApiDocsController.php b/app/Http/Controllers/ApiDocsController.php new file mode 100644 index 0000000000..a75e3d838a --- /dev/null +++ b/app/Http/Controllers/ApiDocsController.php @@ -0,0 +1,40 @@ + array_map(fn (ApiDocsSection $section): array => $section->toArray(), ApiDocsSection::ordered()), + 'current' => $section->value, + 'endpoints' => $section->isGuide() ? [] : $endpoints->get($section), + 'index' => Inertia::once(fn (): array => $endpoints->index()), + 'signing' => $section === ApiDocsSection::Authentication ? $examples->signing() : [], + 'rateLimits' => $section === ApiDocsSection::RateLimits ? $rateLimits->get() : [], + 'snippets' => $snippets->for($section), + 'errorCodes' => $section !== ApiDocsSection::Errors ? [] : array_map(fn (ApiErrorCode $code): array => ['code' => $code->value, 'status' => $code->status(), 'meaning' => $code->meaning()], ApiErrorCode::cases()), + ])->withViewData(['preview' => $metadata->page( + $section->title().' - API docs - /dev/null', + $section->description().'. The JSON API the /dev/null apps use, open to anything you build.', + route('api-docs.show', $section), + )]); + } +} diff --git a/app/Http/Controllers/ApiDocsSchemaController.php b/app/Http/Controllers/ApiDocsSchemaController.php new file mode 100644 index 0000000000..1014310fbd --- /dev/null +++ b/app/Http/Controllers/ApiDocsSchemaController.php @@ -0,0 +1,26 @@ +schemas(ApiDocsSection::from($section), $endpoint); + + return $schemas === null + ? response()->json(['message' => 'Not found.'], 404) + : response()->json($schemas); + } +} diff --git a/app/Http/Middleware/AuthenticateSignedRequest.php b/app/Http/Middleware/AuthenticateSignedRequest.php index cd23e2d492..9e4e89d031 100644 --- a/app/Http/Middleware/AuthenticateSignedRequest.php +++ b/app/Http/Middleware/AuthenticateSignedRequest.php @@ -25,8 +25,6 @@ */ final readonly class AuthenticateSignedRequest { - private const int FailuresPerAddressPerMinute = 60; - public function __construct(private SignedRequests $signedRequests) { // @@ -50,7 +48,7 @@ public function handle(Request $request, Closure $next, ?string $mode = null): R // a ceiling on failures, so a key nobody approved can't make the API check signatures and spend nonces freely... $failures = 'api-signature-failures:'.$request->ip(); - throw_if(RateLimiter::tooManyAttempts($failures, self::FailuresPerAddressPerMinute), fn (): ApiException => new ApiException(ApiErrorCode::RateLimited, 'Too Many Attempts.', [ + throw_if(RateLimiter::tooManyAttempts($failures, SignedRequests::FailuresPerAddressPerMinute), fn (): ApiException => new ApiException(ApiErrorCode::RateLimited, 'Too Many Attempts.', [ 'Retry-After' => RateLimiter::availableIn($failures), ])); diff --git a/app/Http/Middleware/ThrottleCommits.php b/app/Http/Middleware/ThrottleCommits.php index ddaed07333..a29723f7fd 100644 --- a/app/Http/Middleware/ThrottleCommits.php +++ b/app/Http/Middleware/ThrottleCommits.php @@ -6,6 +6,7 @@ use App\Enums\ApiErrorCode; use App\Exceptions\ApiException; +use App\Models\Commit; use App\Models\User; use Closure; use Illuminate\Http\Request; @@ -15,8 +16,6 @@ final readonly class ThrottleCommits { - private const int PER_MINUTE = 10; - /** * One budget of commits a minute, however they are posted. * @@ -29,7 +28,7 @@ public function handle(Request $request, Closure $next): Response $key = "commits:{$user->id}"; - if (RateLimiter::tooManyAttempts($key, self::PER_MINUTE)) { + if (RateLimiter::tooManyAttempts($key, Commit::MAX_PER_MINUTE)) { return $this->slowDown($request, RateLimiter::availableIn($key)); } diff --git a/app/Http/Middleware/ThrottleIssues.php b/app/Http/Middleware/ThrottleIssues.php index 49138d87f3..5d4a756010 100644 --- a/app/Http/Middleware/ThrottleIssues.php +++ b/app/Http/Middleware/ThrottleIssues.php @@ -4,6 +4,7 @@ namespace App\Http\Middleware; +use App\Actions\CreateIssue; use App\Enums\ApiErrorCode; use App\Exceptions\ApiException; use App\Models\User; @@ -14,8 +15,6 @@ final readonly class ThrottleIssues { - private const int PER_DAY = 10; - private const int DECAY_SECONDS = 86400; /** @@ -31,7 +30,7 @@ public function handle(Request $request, Closure $next): Response $key = "issues:{$user->id}"; - if (RateLimiter::tooManyAttempts($key, self::PER_DAY)) { + if (RateLimiter::tooManyAttempts($key, CreateIssue::MAX_PER_DAY)) { return $this->tooMany($request, RateLimiter::availableIn($key)); } @@ -46,7 +45,7 @@ public function handle(Request $request, Closure $next): Response private function tooMany(Request $request, int $retryAfter): Response { - $message = 'Issue limit reached: '.self::PER_DAY.' a day. Try again tomorrow.'; + $message = 'Issue limit reached: '.CreateIssue::MAX_PER_DAY.' a day. Try again tomorrow.'; // The apps read JSON with a code... if ($request->routeIs('api-issue.store')) { diff --git a/app/Http/Resources/ProfileResource.php b/app/Http/Resources/ProfileResource.php index 6e8e49ba1c..6242e12f73 100644 --- a/app/Http/Resources/ProfileResource.php +++ b/app/Http/Resources/ProfileResource.php @@ -23,10 +23,18 @@ public function toArray(Request $request): array { $owner = $this->owner(); + if ($owner instanceof User) { + return [ + 'type' => $this->type, + 'id' => $this->id, + ...UserResource::make($owner)->toArray($request), + ]; + } + return [ 'type' => $this->type, 'id' => $this->id, - ...($owner instanceof User ? UserResource::make($owner) : OrganizationResource::make($owner))->toArray($request), + ...OrganizationResource::make($owner)->toArray($request), ]; } } diff --git a/app/Models/Commit.php b/app/Models/Commit.php index 805af50de6..37532461e4 100644 --- a/app/Models/Commit.php +++ b/app/Models/Commit.php @@ -91,6 +91,11 @@ final class Commit extends Model public const int MAX_BODY_LENGTH = 4000; + /** + * How many commits someone may post a minute, however they post them. + */ + public const int MAX_PER_MINUTE = 10; + /** * Lists show a longer body folded to its first characters and lines, the rest one click away. */ diff --git a/app/OpenApi/ApiDocument.php b/app/OpenApi/ApiDocument.php new file mode 100644 index 0000000000..b9cbd1d860 --- /dev/null +++ b/app/OpenApi/ApiDocument.php @@ -0,0 +1,73 @@ +components->addSecurityScheme(self::SecurityScheme, new ApiKeySecurityScheme('header', 'X-SSH-Signature') + ->as('apiKey') + ->setDescription("An SSH signature, in the `devnull-api` namespace, of the request's `X-Devnull-Timestamp`, `X-Devnull-Nonce`, method, path and query, and body, one per line, made with a key the user approved as a device.")); + + $error = new ObjectType; + $error->addProperty('message', new StringType()->setDescription('What went wrong, as the web says it.')); + $error->addProperty('code', new StringType() + ->enum(array_column(ApiErrorCode::cases(), 'value')) + ->setDescription('Which error it is. A code never changes once released.')); + $error->setRequired(['message', 'code']); + + $document->components->addSchema('ApiError', self::schema($error)); + + $rateLimited = new ObjectType; + $rateLimited->addProperty('message', new StringType()->setDescription('How long to wait, or which limit was reached.')); + $rateLimited->addProperty('code', new StringType() + ->enum([ApiErrorCode::RateLimited->value]) + ->setDescription('Only a signed request gets it, and never from the pings and commit search limits.')); + $rateLimited->setRequired(['message']); + + $document->components->addSchema('RateLimitError', self::schema($rateLimited)); + } + + private static function schema(Type $type): Schema + { + $schema = new Schema; + $schema->type = $type; + + return $schema; + } +} diff --git a/app/OpenApi/ApiRoutes.php b/app/OpenApi/ApiRoutes.php new file mode 100644 index 0000000000..a9cec5b363 --- /dev/null +++ b/app/OpenApi/ApiRoutes.php @@ -0,0 +1,31 @@ +uri()) && ! in_array($route->getName(), self::Excluded, true); + } +} diff --git a/app/OpenApi/ApiTags.php b/app/OpenApi/ApiTags.php new file mode 100644 index 0000000000..0e3df7a142 --- /dev/null +++ b/app/OpenApi/ApiTags.php @@ -0,0 +1,45 @@ + 'me', + 'starred' => 'me', + ]; + + /** + * @return list + */ + public function __invoke(RouteInfo $routeInfo): array + { + $segment = Str::of($routeInfo->route->uri())->after('api/v1/')->before('/')->value(); + $section = ApiDocsSection::tryFrom(self::Aliases[$segment] ?? $segment); + + throw_unless($section, fn (): LogicException => new LogicException("The API docs have no group for /{$segment}: add it to ".ApiDocsSection::class.', or alias it in '.self::class.'.')); + + return [$section->title()]; + } + + /** + * @return list + */ + public static function tags(): array + { + return array_map(fn (ApiDocsSection $section): Tag => new Tag($section->title()), ApiDocsSection::reference()); + } +} diff --git a/app/OpenApi/CommitBodyLengthRule.php b/app/OpenApi/CommitBodyLengthRule.php new file mode 100644 index 0000000000..b9d125c027 --- /dev/null +++ b/app/OpenApi/CommitBodyLengthRule.php @@ -0,0 +1,37 @@ +instanceOf(CommitBodyLength::class); + } + + public function toSchema(Type $previous, NormalizedRule $rule, RuleTransformerContext $context): Type + { + return $previous->setDescription(sprintf( + 'At most %s characters, where a link outside code counts as %d at most. Each link must be %s characters at most.', + Number::format(Commit::MAX_BODY_LENGTH, locale: 'en'), + Urls::MAX_COUNTED_LENGTH, + Number::format(Urls::MAX_LENGTH, locale: 'en'), + )); + } +} diff --git a/app/OpenApi/ContainerResolution.php b/app/OpenApi/ContainerResolution.php new file mode 100644 index 0000000000..84c10739bc --- /dev/null +++ b/app/OpenApi/ContainerResolution.php @@ -0,0 +1,32 @@ +getArg('name', 0); + + return $abstract instanceof GenericClassStringType && $abstract->type instanceof ObjectType + ? $abstract->type + : null; + } +} diff --git a/app/OpenApi/OptionalPolls.php b/app/OpenApi/OptionalPolls.php new file mode 100644 index 0000000000..45fc3a9b0e --- /dev/null +++ b/app/OpenApi/OptionalPolls.php @@ -0,0 +1,37 @@ +components->schemas)->first(fn (mixed $schema, string $key): bool => preg_replace('/^.*[.\\\\]/', '', $key) === $name); + $fields = $request instanceof Schema ? $request->type : null; + $poll = $fields instanceof ObjectType ? $fields->properties['poll'] ?? null : null; + + throw_unless($fields instanceof ObjectType && $poll instanceof ObjectType, fn (): LogicException => new LogicException("{$name} no longer takes a poll object: update ".self::class.'.')); + + $fields->required = array_values(array_diff($fields->required, ['poll'])); + $poll->setRequired(['options', 'duration']); + $poll->nullable(true); + } + } +} diff --git a/app/OpenApi/PathParameters.php b/app/OpenApi/PathParameters.php new file mode 100644 index 0000000000..537dab6c6f --- /dev/null +++ b/app/OpenApi/PathParameters.php @@ -0,0 +1,64 @@ +path, $documented); + preg_match_all('/\{(\w+)\??\}/', $routeInfo->route->uri(), $routed); + + $fields = $routeInfo->route->bindingFields(); + $parameters = []; + + foreach ($documented[1] as $index => $name) { + $model = $routed[1][$index] ?? $name; + $field = is_string($fields[$model] ?? null) ? $fields[$model] : null; + $parameters[$name] = ['name' => $field ?? $model, 'field' => $field, 'model' => $model]; + } + + $names = array_column($parameters, 'name'); + $twice = array_diff_assoc($names, array_unique($names)); + + throw_if($twice !== [], fn (): LogicException => new LogicException("Two path parameters of {$operation->path} would both be named {".reset($twice).'}.')); + + $operation->setPath((string) preg_replace_callback( + '/\{(\w+)\}/', + fn (array $match): string => '{'.($parameters[$match[1]]['name'] ?? $match[1]).'}', + $operation->path, + )); + + foreach ($operation->parameters as $parameter) { + if (! $parameter instanceof Parameter || $parameter->in !== 'path' || ! isset($parameters[$parameter->name])) { + continue; + } + + $routed = $parameters[$parameter->name]; + $parameter->name = $routed['name']; + + if ($routed['field'] !== null) { + $schema = new Schema; + $schema->type = new StringType; + $parameter->setSchema($schema); + $parameter->description = 'The '.Str::of($routed['model'])->snake(' ')->value()."'s {$routed['field']}"; + } + } + } +} diff --git a/app/OpenApi/RateLimitResponses.php b/app/OpenApi/RateLimitResponses.php new file mode 100644 index 0000000000..96556b6526 --- /dev/null +++ b/app/OpenApi/RateLimitResponses.php @@ -0,0 +1,27 @@ +route->gatherMiddleware())->contains(fn (mixed $middleware): bool => is_string($middleware) && Str::startsWith($middleware, 'throttle:'))) { + $operation->addResponse(Response::make(429) + ->setDescription('Too many requests. Wait for the `Retry-After` seconds before trying again.') + ->setContent('application/json', ApiDocument::rateLimitError())); + } + } +} diff --git a/app/OpenApi/SignatureSecurity.php b/app/OpenApi/SignatureSecurity.php new file mode 100644 index 0000000000..5cd1df853a --- /dev/null +++ b/app/OpenApi/SignatureSecurity.php @@ -0,0 +1,40 @@ +route->gatherMiddleware(), is_string(...))); + $isOptional = in_array(self::Middleware.':optional', $middleware, true); + $isRequired = in_array(self::Middleware, $middleware, true); + $signed = new SecurityRequirement([ApiDocument::SecurityScheme => []]); + + $operation->security = $isOptional ? [new SecurityRequirement([]), $signed] : ($isRequired ? [$signed] : []); + + if ($isOptional || $isRequired) { + $operation->addResponse(Response::make(401) + ->setDescription($isOptional + ? 'The signature is stale or wrong, or the key that made it is not an approved device. Without one, the request reads as a guest.' + : 'The signature is missing, stale or wrong, or the key that made it is not an approved device.') + ->setContent('application/json', ApiDocument::error())); + } + } +} diff --git a/app/OpenApi/SignedUploads.php b/app/OpenApi/SignedUploads.php new file mode 100644 index 0000000000..851fd3a102 --- /dev/null +++ b/app/OpenApi/SignedUploads.php @@ -0,0 +1,104 @@ +paths as $path) { + foreach ($path->operations as $operation) { + $body = $operation->requestBodyObject; + $media = $body instanceof RequestBodyObject && isset($body->content[self::Multipart]) ? $body->getContent(self::Multipart) : null; + $json = $media instanceof MediaType ? $media->schema : null; + $schema = $json instanceof Reference ? $json->resolve() : $json; + $fields = $schema instanceof Schema ? $schema->type : null; + + if (! $body instanceof RequestBodyObject || ! $json instanceof Schema && ! $json instanceof Reference || ! $fields instanceof ObjectType) { + continue; + } + + $files = $this->takeFiles($fields); + + $body->content = []; + $body->setContent('application/json', $json); + $body->setContent(self::Multipart, $this->upload($files)); + } + } + } + + /** + * @return array + */ + private function takeFiles(ObjectType $fields): array + { + $files = []; + + foreach ($fields->properties as $name => $type) { + if ($type !== null && $this->isFile($type)) { + $files[$name] = $type; + unset($fields->properties[$name]); + } + } + + $fields->required = array_values(array_diff($fields->required, array_keys($files))); + + return $files; + } + + private function isFile(Type $type): bool + { + $item = $type instanceof ArrayType ? $type->items : $type; + + return $item instanceof StringType && $item->format === 'binary'; + } + + /** + * The JSON and its files, all required: a request without files sends the JSON alone, and the API refuses an upload + * that has none (see SignedRequests::payload()). + * + * @param array $files + */ + private function upload(array $files): Schema + { + $payload = new StringType; + $payload->format = 'binary'; + $payload->contentMediaType = 'application/json'; + $payload->setDescription("The request's fields, as the JSON body would send them, in a file part."); + + $upload = new ObjectType; + $upload->addProperty('payload', $payload); + + foreach ($files as $name => $file) { + $upload->addProperty($name, $file->nullable(false)); + } + + $upload->setRequired(['payload', ...array_keys($files)]); + + $schema = new Schema; + $schema->type = $upload; + + return $schema; + } +} diff --git a/app/Providers/ApiDocumentationServiceProvider.php b/app/Providers/ApiDocumentationServiceProvider.php new file mode 100644 index 0000000000..775349b970 --- /dev/null +++ b/app/Providers/ApiDocumentationServiceProvider.php @@ -0,0 +1,56 @@ +configure(); + } + } + + private function configure(): void + { + Scramble::resolveTagsUsing(new ApiTags); + Scramble::registerExtension(ContainerResolution::class); + + $config = Scramble::configure(); + + $config->routes(new ApiRoutes()(...)); + $config->withTags(ApiTags::tags()); + $config->withOperationTransformers([PathParameters::class, SignatureSecurity::class, RateLimitResponses::class]); + $config->withRuleTransformers(CommitBodyLengthRule::class); + $config->withDocumentTransformers([ApiDocument::class, SignedUploads::class, OptionalPolls::class]); + } +} diff --git a/app/Queries/ApiDocsQuery.php b/app/Queries/ApiDocsQuery.php new file mode 100644 index 0000000000..ac0139e698 --- /dev/null +++ b/app/Queries/ApiDocsQuery.php @@ -0,0 +1,576 @@ +|null, children: list>} + * @phpstan-type Parameter array{in: string, name: string, type: string, required: bool, description: string|null, enum: list|null, children: list>} + * @phpstan-type Schema array{code: string, html: string} + * @phpstan-type Endpoint array{ + * id: string, + * method: string, + * path: string, + * summary: string, + * description: string|null, + * signature: 'required'|'optional', + * parameters: list, + * body: array{mediaType: string, fields: list}|null, + * responses: list}>, + * examples: list + * } + */ +final readonly class ApiDocsQuery +{ + private const int Depth = 3; + + private const array SchemaKeywords = ['additionalProperties', 'items', 'additionalItems', 'unevaluatedProperties', 'unevaluatedItems', 'contains', 'propertyNames', 'not', 'if', 'then', 'else']; + + private const array SchemaMapKeywords = ['properties', 'patternProperties', 'dependentSchemas', '$defs']; + + private const array SchemaListKeywords = ['allOf', 'anyOf', 'oneOf', 'prefixItems']; + + /** + * What the cached docs were made from: the spec, the code that reads and highlights it. Any of them changing makes + * the cache stale. + */ + private string $version; + + public function __construct(private ApiExamples $examples, private Highlighter $highlighter, private ?string $path = null) + { + $files = [$this->specPath(), __FILE__, (string) new ReflectionClass(ApiExamples::class)->getFileName(), (string) new ReflectionClass(ApiDocsSection::class)->getFileName()]; + + $this->version = implode(':', [ + ...array_map(fn (string $file): string => (string) hash_file('xxh128', $file), $files), + InstalledVersions::getReference('tempest/highlight') ?? '', + ]); + } + + /** + * @return list + */ + public function get(ApiDocsSection $section): array + { + return $this->remember("api-docs:{$section->value}", fn (): array => $this->endpoints($this->spec(), $section)); + } + + /** + * The JSON schemas of an endpoint's body and of the answers whose fields its docs detail, by status. They are + * only read for the endpoint a reader asks them for, and only for an endpoint the group has, so a made-up one + * costs nothing to keep. + * + * @return array{body: Schema|null, responses: array}|null + */ + public function schemas(ApiDocsSection $section, string $id): ?array + { + if (! in_array($id, array_column($this->get($section), 'id'), true)) { + return null; + } + + return $this->remember("api-docs-schemas:{$section->value}:{$id}", fn (): array => $this->endpointSchemas($this->spec(), $section, $id)); + } + + /** + * Every endpoint of the reference in a line, for searching them from any page of the docs. + * + * @return list + */ + public function index(): array + { + return $this->remember('api-docs-index', fn (): array => array_merge(...array_map(fn (ApiDocsSection $section): array => array_map(fn (array $endpoint): array => [ + 'id' => $endpoint['id'], + 'method' => $endpoint['method'], + 'path' => $endpoint['path'], + 'summary' => $endpoint['summary'], + 'section' => $section->value, + ], $this->get($section)), ApiDocsSection::reference()))); + } + + /** + * What a key holds for this version, made again and put in its place when it was made from another. + * + * @template T + * + * @param Closure(): T $make + * @return T + */ + private function remember(string $key, Closure $make): mixed + { + $fresh = fn (): array => ['version' => $this->version, 'data' => $make()]; + $entry = Cache::rememberForever($key, $fresh); + + if ($entry['version'] !== $this->version) { + $entry = $fresh(); + Cache::forever($key, $entry); + } + + return $entry['data']; + } + + private function specPath(): string + { + return $this->path ?? resource_path('api/openapi.json'); + } + + /** + * @return array + */ + private function spec(): array + { + return $this->map(json_decode(File::get($this->specPath()), true, flags: JSON_THROW_ON_ERROR)); + } + + /** + * @param array $spec + * @return array{body: Schema|null, responses: array} + */ + private function endpointSchemas(array $spec, ApiDocsSection $section, string $id): array + { + $schemas = $this->map($this->map($spec['components'] ?? null)['schemas'] ?? null); + $responses = $this->map($this->map($spec['components'] ?? null)['responses'] ?? null); + $operation = $this->operations($spec, $section)[$id]['operation'] ?? []; + $answers = []; + + foreach ($this->map($operation['responses'] ?? null) as $status => $response) { + [, $schema, $detailed] = $this->answer((string) $status, $this->map($response), $responses); + + if ($detailed && ($written = $this->schema($schema, $schemas)) !== null) { + $answers[(string) $status] = $written; + } + } + + return [ + 'body' => $this->schema($this->map($this->map(Arr::first($this->map($this->map($operation['requestBody'] ?? null)['content'] ?? null)))['schema'] ?? null), $schemas), + 'responses' => $answers, + ]; + } + + /** + * The operations of a group by the ID the docs give them, the spec's own or one made from the method and path, so + * the reference and an endpoint's schemas find it by the same name. + * + * @param array $spec + * @return array}> + */ + private function operations(array $spec, ApiDocsSection $section): array + { + $operations = []; + $anchors = []; + + foreach ($this->map($spec['paths'] ?? null) as $path => $item) { + foreach ($this->map($item) as $method => $operation) { + $operation = $this->map($operation); + + if (in_array($section->title(), $this->map($operation['tags'] ?? null), true)) { + $id = $this->text($operation['operationId'] ?? null) ?? $method.'-'.mb_trim((string) preg_replace('/[^A-Za-z0-9]+/', '-', (string) $path), '-'); + + $anchor = (string) preg_replace('/[^A-Za-z0-9_-]+/', '-', $id); + + throw_if(isset($anchors[$anchor]), fn (): LogicException => new LogicException("Two endpoints of the API docs would both be named {$anchor}.")); + + $anchors[$anchor] = true; + + $operations[$id] = ['path' => (string) $path, 'method' => (string) $method, 'operation' => $operation]; + } + } + } + + return $operations; + } + + /** + * @param array $spec + * @return list + */ + private function endpoints(array $spec, ApiDocsSection $section): array + { + $schemas = $this->map($this->map($spec['components'] ?? null)['schemas'] ?? null); + $responses = $this->map($this->map($spec['components'] ?? null)['responses'] ?? null); + $operations = $this->operations($spec, $section); + + return array_map( + fn (string $id, array $entry): array => $this->endpoint($id, $entry['path'], $entry['method'], $entry['operation'], $responses, $schemas), + array_keys($operations), + array_values($operations), + ); + } + + /** + * @param array $operation + * @param array $responses + * @param array $schemas + * @return Endpoint + */ + private function endpoint(string $id, string $path, string $method, array $operation, array $responses, array $schemas): array + { + $body = $this->map($this->map($operation['requestBody'] ?? null)['content'] ?? null); + $mediaType = array_key_first($body); + + $endpoint = [ + 'id' => $id, + 'method' => mb_strtoupper($method), + 'path' => $path, + 'summary' => $this->text($operation['summary'] ?? null) ?? '', + 'description' => $this->text($operation['description'] ?? null) ?: null, + 'signature' => $this->map($operation['security'] ?? null) === [] || in_array([], $this->map($operation['security']), true) ? 'optional' : 'required', + 'parameters' => array_map(fn (mixed $parameter): array => $this->parameter($parameter, $schemas), array_values($this->map($operation['parameters'] ?? null))), + 'body' => $mediaType === null ? null : [ + 'mediaType' => (string) $mediaType, + 'fields' => $this->fields($this->map($this->map($body[$mediaType])['schema'] ?? null), $schemas, 0, []), + ], + 'responses' => array_map( + fn (mixed $status, mixed $response): array => $this->response((string) $status, $this->map($response), $responses, $schemas), + array_keys($this->map($operation['responses'] ?? null)), + array_values($this->map($operation['responses'] ?? null)), + ), + ]; + + return [...$endpoint, 'examples' => $this->examples->for($endpoint)]; + } + + /** + * An answer, with the fields it holds when it succeeds, or when it is an error only this endpoint answers with. + * The errors every endpoint shares, the API's own and Laravel's, are left to the Errors guide. + * + * @param array $response + * @param array $responses + * @param array $schemas + * @return array{status: string, description: string, fields: list} + */ + private function response(string $status, array $response, array $responses, array $schemas): array + { + [$response, $schema, $detailed] = $this->answer($status, $response, $responses); + + return [ + 'status' => $status, + 'description' => $this->text($response['description'] ?? null) ?? '', + 'fields' => $detailed ? $this->fields($schema, $schemas, 0, []) : [], + ]; + } + + /** + * An answer as the spec gives it, a shared one followed to its component, its schema, and whether the docs detail + * it: a success always, an error only when it is this endpoint's own. + * + * @param array $response + * @param array $responses + * @return array{array, array, bool} + */ + private function answer(string $status, array $response, array $responses): array + { + $shared = isset($response['$ref']); + $response = $shared ? $this->map($responses[Str::afterLast($this->text($response['$ref']) ?? '', '/')] ?? null) : $response; + $schema = $this->map($this->map(Arr::first($this->map($response['content'] ?? null)))['schema'] ?? null); + + return [$response, $schema, str_starts_with($status, '2') || (! $shared && ! isset($schema['$ref']))]; + } + + /** + * The JSON schema of a body or an answer as a reader can follow it, on its own: the schema itself, and every + * schema it refers to written once in its `$defs`, so a commit's parent points back at Commit instead of looping, + * and a resource used in many places weighs once. + * + * @param array $schema + * @param array $schemas + * @return Schema|null + */ + private function schema(array $schema, array $schemas): ?array + { + if ($schema === []) { + return null; + } + + $defs = []; + $root = $this->inline($schemas[Str::afterLast($this->text($schema['$ref'] ?? null) ?? '', '/')] ?? $schema, $schemas, $defs); + $document = $defs === [] ? $root : [...$this->map($root), '$defs' => $defs]; + $code = (string) json_encode($document, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE); + + return ['code' => $code, 'html' => $this->highlighter->parse($code, 'json')]; + } + + /** + * A schema with its references pointing at `$defs`, and each schema they name written there once. + * + * @param array $schemas + * @param array $defs + */ + private function inline(mixed $schema, array $schemas, array &$defs, string $kind = 'schema'): mixed + { + if (! is_array($schema)) { + return $schema; + } + + if ($schema === []) { + return in_array($kind, ['schema', 'map'], true) ? new stdClass : []; + } + + $reference = $kind === 'schema' ? $this->text($schema['$ref'] ?? null) : null; + + if ($reference === null) { + foreach ($schema as $key => $value) { + $schema[$key] = $this->inline($value, $schemas, $defs, $this->kindOf($kind, (string) $key)); + } + + return $schema; + } + + $name = Str::afterLast($reference, '/'); + + if (isset($schemas[$name]) && ! array_key_exists($name, $defs)) { + $defs[$name] = null; + $defs[$name] = $this->inline($schemas[$name], $schemas, $defs); + } + + return ['$ref' => isset($schemas[$name]) ? "#/\$defs/{$name}" : $reference]; + } + + /** + * What a value under a key is, in JSON Schema terms: a schema, a map or a list of schemas, or plain data. The spec + * is read as PHP arrays, which can't tell `{}` from `[]`, so an empty schema or map is written back as an object + * and anything else empty as a list. + */ + private function kindOf(string $parent, string $key): string + { + return match (true) { + $parent === 'map', $parent === 'list' => 'schema', + $parent !== 'schema' => 'data', + in_array($key, self::SchemaKeywords, true) => 'schema', + in_array($key, self::SchemaMapKeywords, true) => 'map', + in_array($key, self::SchemaListKeywords, true) => 'list', + default => 'data', + }; + } + + /** + * A path or query parameter. A path always has its parameters, so none of them is ever null. + * + * @param array $schemas + * @return Parameter + */ + private function parameter(mixed $parameter, array $schemas): array + { + $parameter = $this->map($parameter); + $in = $this->text($parameter['in'] ?? null) ?? 'query'; + $field = $this->field( + $this->text($parameter['name'] ?? null) ?? '', + [...$this->map($parameter['schema'] ?? null), 'description' => $parameter['description'] ?? null], + ($parameter['required'] ?? false) === true, + $schemas, + 0, + [], + ); + + return [ + 'in' => $in, + ...$field, + 'type' => $in === 'path' ? Str::replace(' | null', '', $field['type']) : $field['type'], + ]; + } + + /** + * The fields of an object, those of every schema it is all of, or of any it may be, which are only required when + * every one of them requires it. + * + * @param array $schema + * @param array $schemas + * @param list $seen + * @return list + */ + private function fields(array $schema, array $schemas, int $depth, array $seen): array + { + [$schema, $seen] = $this->resolve($schema, $schemas, $seen); + $through = []; + + while (isset($schema['items'])) { + $items = $this->map($schema['items']); + $names = $this->refers($items, $schemas); + + if (array_intersect($names, $through) !== []) { + return []; + } + + $through = [...$through, ...$names]; + [$schema, $seen] = $this->resolve($items, $schemas, $seen); + } + + $parts = array_map(fn (mixed $part): array => $this->resolve($this->map($part), $schemas, $seen)[0], $this->map($schema['allOf'] ?? $schema['anyOf'] ?? $schema['oneOf'] ?? null)); + + if ($parts !== []) { + $required = isset($schema['allOf']) + ? array_merge(...array_map(fn (array $part): array => $this->map($part['required'] ?? null), $parts)) + : array_intersect(...array_map(fn (array $part): array => $this->map($part['required'] ?? null), $parts)); + + $properties = array_merge(...array_map(fn (array $part): array => $this->map($part['properties'] ?? null), $parts)); + + return $this->properties($properties, array_values($required), $schemas, $depth, $seen); + } + + return $this->properties($this->map($schema['properties'] ?? null), array_values($this->map($schema['required'] ?? null)), $schemas, $depth, $seen); + } + + /** + * @param array $properties + * @param list $required + * @param array $schemas + * @param list $seen + * @return list + */ + private function properties(array $properties, array $required, array $schemas, int $depth, array $seen): array + { + return array_map( + fn (mixed $name, mixed $schema): array => $this->field((string) $name, $this->map($schema), in_array($name, $required, true), $schemas, $depth, $seen), + array_keys($properties), + array_values($properties), + ); + } + + /** + * @param array $schema + * @param array $schemas + * @param list $seen + * @return Field + */ + private function field(string $name, array $schema, bool $required, array $schemas, int $depth, array $seen): array + { + $resolved = $this->resolve($schema, $schemas, $seen)[0]; + $refers = $this->refers($schema, $schemas); + $describable = $depth + 1 < self::Depth && ! array_intersect($refers, $seen) && $this->isObject($resolved, $schemas); + + return [ + 'name' => $name, + 'type' => $this->type($schema, $schemas), + 'required' => $required, + 'description' => $this->text($schema['description'] ?? null) ?? $this->text($resolved['description'] ?? null), + 'enum' => isset($resolved['enum']) || isset($resolved['const']) + ? array_values(array_filter($this->map($resolved['enum'] ?? [$resolved['const']]), fn (mixed $value): bool => is_string($value) || is_int($value))) + : null, + 'children' => $describable ? $this->fields($schema, $schemas, $depth + 1, [...$seen, ...$refers]) : [], + ]; + } + + /** + * Follows a reference to the schema it names, and remembers that schema is being described. + * + * @param array $schema + * @param array $schemas + * @param list $seen + * @return array{array, list} + */ + private function resolve(array $schema, array $schemas, array $seen): array + { + $reference = $this->text($schema['$ref'] ?? null); + + if ($reference === null) { + return [$schema, $seen]; + } + + $name = Str::afterLast($reference, '/'); + + return [$this->map($schemas[$name] ?? null), [...$seen, $name]]; + } + + /** + * The named schemas a schema is, or may be, itself or as the items of its list. + * + * @param array $schema + * @param array $schemas + * @return list + */ + private function refers(array $schema, array $schemas): array + { + if (($reference = $this->text($schema['$ref'] ?? null)) !== null) { + return [Str::afterLast($reference, '/')]; + } + + if (isset($schema['items'])) { + return $this->refers($this->map($schema['items']), $schemas); + } + + return array_merge(...array_map(fn (mixed $part): array => $this->refers($this->map($part), $schemas), array_values($this->map($schema['anyOf'] ?? $schema['oneOf'] ?? null)))); + } + + /** + * @param array $schema + * @param array $schemas + */ + private function isObject(array $schema, array $schemas): bool + { + if (isset($schema['items'])) { + return $this->isObject($this->resolve($this->map($schema['items']), $schemas, [])[0], $schemas); + } + + return isset($schema['properties']) || isset($schema['allOf']) || isset($schema['anyOf']) || isset($schema['oneOf']); + } + + /** + * What a schema is, as a reader would say it: `uuid`, `string | null`, `array of Commit`, `User | Organization`. + * + * @param array $schema + * @param array $schemas + */ + private function type(array $schema, array $schemas): string + { + if (($reference = $this->text($schema['$ref'] ?? null)) !== null) { + return Str::of($reference)->afterLast('/')->replaceEnd('Resource', '')->value(); + } + + $parts = $this->map($schema['anyOf'] ?? $schema['oneOf'] ?? null); + + if ($parts !== []) { + return implode(' | ', array_unique(array_map(fn (mixed $part): string => $this->type($this->map($part), $schemas), $parts))); + } + + if (isset($schema['allOf'])) { + return 'object'; + } + + $types = is_array($schema['type'] ?? null) ? $schema['type'] : [$schema['type'] ?? 'object']; + + return implode(' | ', array_map(fn (mixed $type): string => match (true) { + $type === 'array' => 'array of '.$this->items($this->type($this->map($schema['items'] ?? null), $schemas)), + $type === 'string' && is_string($schema['format'] ?? null) => $schema['format'], + default => is_string($type) ? $type : 'mixed', + }, $types)); + } + + /** + * What a list holds, in parentheses when it may be one of several, so `array of (string | null) | null` reads as + * a list that may be null of strings that may be null. + */ + private function items(string $type): string + { + return str_contains($type, ' | ') ? "({$type})" : $type; + } + + /** + * @return array + */ + private function map(mixed $value): array + { + return is_array($value) ? $value : []; + } + + private function text(mixed $value): ?string + { + return is_string($value) ? $value : null; + } +} diff --git a/app/Queries/ApiRateLimitsQuery.php b/app/Queries/ApiRateLimitsQuery.php new file mode 100644 index 0000000000..180ab48a5c --- /dev/null +++ b/app/Queries/ApiRateLimitsQuery.php @@ -0,0 +1,107 @@ + 'minute', 3600 => 'hour', 86400 => 'day']; + + /** + * @return list + */ + public function get(): array + { + return [ + ...$this->limiter('Unsigned requests', 'api', signed: false, scope: 'per IP'), + ...$this->limiter('Signed requests', 'api', scope: 'per person'), + $this->row('Signatures that fail to check out', SignedRequests::FailuresPerAddressPerMinute, 60, 'per IP'), + $this->row('Commits, replies and quotes, now or scheduled', Commit::MAX_PER_MINUTE, 60, 'shared with the web and the terminal'), + ...$this->limiter('Commit searches', 'search'), + ...$this->limiter('People searches, mention suggestions and profile cards', 'people'), + ...$this->limiter('Issue suggestions', 'issue-suggestions'), + ...$this->limiter('Stars', 'stars'), + ...$this->limiter('Pins', 'pins'), + ...$this->limiter('Follows', 'follows'), + $this->route('Pastéis', 'api-commit-pastel.store'), + $this->route('Translations', 'api-commit-translation.store'), + ...$this->limiter('Reports', 'commit-reports'), + $this->route('Organization claims', 'api-organization-admin.store'), + ...$this->limiter('Syncs from GitHub', 'profile-syncs'), + $this->route('Feature requests and bug reports', 'api-issue.store'), + $this->row('Feature requests and bug reports opened on GitHub', CreateIssue::MAX_PER_DAY, 86400, 'shared with the web'), + ...$this->limiter('Reading and polling remotes', 'conversations'), + ...$this->limiter('Messages', 'messages'), + ...$this->limiter('Pings', 'pings'), + ]; + } + + /** + * A named limiter's budgets, as it sets them for a signed request, or an unsigned one. + * + * @return list + */ + private function limiter(string $what, string $name, bool $signed = true, ?string $scope = null): array + { + $limiter = RateLimiter::limiter($name); + + throw_unless($limiter, fn (): LogicException => new LogicException("No rate limiter is named {$name}.")); + + $limits = array_filter(Arr::wrap($limiter($this->request($signed))), fn (mixed $limit): bool => $limit instanceof Limit); + + return array_values(array_map(fn (Limit $limit): array => $this->row($what, $limit->maxAttempts, $limit->decaySeconds, $scope), $limits)); + } + + /** + * The budget a route sets itself, as `throttle:attempts,minutes`. + * + * @return array{what: string, limit: int, per: string} + */ + private function route(string $what, string $name): array + { + $throttle = collect(Route::getRoutes()->getByName($name)?->gatherMiddleware() ?? []) + ->map(fn (mixed $middleware): array => is_string($middleware) && preg_match('/^throttle:(\d+),(\d+)/', $middleware, $match) === 1 ? [(int) $match[1], (int) $match[2]] : []) + ->first(fn (array $throttle): bool => $throttle !== []); + + throw_unless($throttle, fn (): LogicException => new LogicException("The route {$name} sets no budget of its own.")); + + return $this->row($what, $throttle[0], $throttle[1] * 60); + } + + /** + * @return array{what: string, limit: int, per: string} + */ + private function row(string $what, int $limit, int $seconds, ?string $scope = null): array + { + $per = self::Units[$seconds] ?? "{$seconds} seconds"; + + return ['what' => $what, 'limit' => $limit, 'per' => $scope === null ? $per : "{$per}, {$scope}"]; + } + + private function request(bool $signed): Request + { + $request = Request::create('/api/v1', server: ['REMOTE_ADDR' => '192.0.2.1']); + + if ($signed) { + $request->setUserResolver(fn (): User => new User()->forceFill(['id' => '00000000-0000-7000-8000-000000000000'])); + } + + return $request; + } +} diff --git a/app/Services/ApiExamples.php b/app/Services/ApiExamples.php new file mode 100644 index 0000000000..e3bdae0f3c --- /dev/null +++ b/app/Services/ApiExamples.php @@ -0,0 +1,405 @@ + self::Tomorrow, + 'timezone' => 'Europe/Paris', + 'url' => 'https://www.twitch.tv/nunomaduro', + 'sdp' => 'v=0…', + 'handle' => 'nunomaduro', + 'commit' => '01a1c63c-ae57-70cc-adf3-2298cc075627', + 'org' => self::Uuid, + 'scheduledCommit' => self::Uuid, + 'device' => self::Uuid, + 'notification' => self::Uuid, + 'headline' => self::Uuid, + 'message' => '1', + 'log' => 'following', + 'body' => 'Hello from the API!', + 'name' => 'The Artisans', + 'q' => 'laravel', + 'emoji' => '👍', + ]; + + /** + * Query values that only make sense on one path, by path then name. + */ + private const array QuerySamples = [ + '/search/issues' => ['q' => '857'], + ]; + + public function __construct(private Highlighter $highlighter) + { + // + } + + /** + * @param array $endpoint + * @return list + */ + public function for(array $endpoint): array + { + $method = is_string($endpoint['method'] ?? null) ? $endpoint['method'] : 'GET'; + $path = $this->path(is_string($endpoint['path'] ?? null) ? $endpoint['path'] : '/', $this->list($endpoint['parameters'] ?? null)); + $fields = $this->list(is_array($endpoint['body'] ?? null) ? $endpoint['body']['fields'] ?? null : null); + $body = $this->body($fields) ?? $this->body($fields, everyField: true); + $signed = ($endpoint['signature'] ?? null) === 'required'; + $answers = ! in_array('204', array_column($this->list($endpoint['responses'] ?? null), 'status'), true); + + return $this->highlight([ + ['label' => 'curl', 'language' => 'bash', 'code' => $this->curl($method, $path, $body, $signed)], + ['label' => 'Laravel', 'language' => 'php', 'code' => $this->laravel($method, $path, $body, $signed)], + ['label' => 'fetch', 'language' => 'javascript', 'code' => $this->fetch($method, $path, $body, $signed, $answers)], + ]); + } + + /** + * How each client signs a request, once, for Authentication: what every signed example calls. + * + * @return list + */ + public function signing(): array + { + return $this->highlight([ + ['label' => 'curl', 'language' => 'bash', 'code' => <<<'SH' + # devnull_sign METHOD PATH [BODY] sets $ts, $nonce and $signature + devnull_sign() { + ts=$(date +%s) + nonce=$(openssl rand -hex 16) + signature=$(printf '%s\n%s\n%s\n%s\n%s' "$ts" "$nonce" "$1" "$2" "${3-}" \ + | ssh-keygen -Y sign -n devnull-api -f ~/.ssh/devnull -q \ + | sed '1d;$d' | tr -d '\n') + } + SH], + ['label' => 'Laravel', 'language' => 'php', 'code' => <<<'PHP' + use Illuminate\Support\Facades\Process; + use Illuminate\Support\Str; + + /** + * The headers that sign a request to the /dev/null API. + * + * @return array + */ + function devnullHeaders(string $method, string $path, string $body = ''): array + { + $timestamp = (string) time(); + $nonce = bin2hex(random_bytes(16)); + $signature = Str::of(Process::input(implode("\n", [$timestamp, $nonce, $method, $path, $body])) + ->run(['ssh-keygen', '-Y', 'sign', '-n', 'devnull-api', '-f', getenv('HOME').'/.ssh/devnull', '-q']) + ->throw() + ->output()) + ->replaceMatches('/-----[A-Z ]+-----|\s/', '') + ->value(); + + return [ + 'X-Devnull-Timestamp' => $timestamp, + 'X-Devnull-Nonce' => $nonce, + 'X-SSH-Signature' => $signature, + ]; + } + PHP], + ['label' => 'fetch', 'language' => 'javascript', 'code' => <<<'JS' + // devnull.mjs, for Node.js, with ssh-keygen on the PATH + import { execFileSync } from 'node:child_process'; + import { randomBytes } from 'node:crypto'; + import { homedir } from 'node:os'; + + // The headers that sign a request to the /dev/null API. + export function devnullHeaders(method, path, body = '') { + const timestamp = String(Math.floor(Date.now() / 1000)); + const nonce = randomBytes(16).toString('hex'); + const signature = execFileSync( + 'ssh-keygen', + ['-Y', 'sign', '-n', 'devnull-api', '-f', `${homedir()}/.ssh/devnull`, '-q'], + { input: [timestamp, nonce, method, path, body].join('\n') }, + ) + .toString() + .replace(/-----[A-Z ]+-----|\s/g, ''); + + return { + 'X-Devnull-Timestamp': timestamp, + 'X-Devnull-Nonce': nonce, + 'X-SSH-Signature': signature, + }; + } + JS], + ]); + } + + /** + * @param list $examples + * @return list + */ + private function highlight(array $examples): array + { + return array_map(fn (array $example): array => [ + ...$example, + 'html' => $this->highlighter->parse($example['code'], $example['language']), + ], $examples); + } + + /** + * A shell script: the body in a variable when there is one, so the signature covers the very bytes curl sends. + * + * @param array|null $body + */ + private function curl(string $method, string $path, ?array $body, bool $signed): string + { + $url = self::BaseUrl.$path; + $lines = [($method === 'GET' ? 'curl ' : "curl -X {$method} ").(str_contains($url, '?') ? "'{$url}'" : $url), "-H 'Accept: application/json'"]; + + if ($signed) { + $lines = [...$lines, '-H "X-Devnull-Timestamp: $ts"', '-H "X-Devnull-Nonce: $nonce"', '-H "X-SSH-Signature: $signature"']; + } + + $json = $body === null ? '' : str_replace(self::Tomorrow, '\'"$tomorrow"\'', $this->shell($this->json($body))); + $tomorrow = str_contains($json, '$tomorrow') ? ['tomorrow=$(date -u -d tomorrow +%Y-%m-%dT%H:%M:%S+00:00 2>/dev/null || date -u -v+1d +%Y-%m-%dT%H:%M:%S+00:00)'] : []; + + if ($body !== null) { + $lines = [...$lines, "-H 'Content-Type: application/json'", $signed ? '-d "$body"' : "-d {$json}"]; + } + + $request = implode(" \\\n ", $lines); + + if (! $signed) { + return implode("\n", [...$tomorrow, $request]); + } + + return implode("\n", [ + ...$tomorrow, + ...($body === null ? [] : ["body={$json}"]), + "devnull_sign {$method} '".self::SignedPrefix.$path."'".($body === null ? '' : ' "$body"').' # see Authentication', + '', + $request, + ]); + } + + /** + * Laravel's HTTP client, its headers from devnullHeaders(), over the body it then sends as it is. A write without a + * body goes through send(): post() and put() given nothing send `[]`, which a signature over nothing doesn't cover. + * + * @param array|null $body + */ + private function laravel(string $method, string $path, ?array $body, bool $signed): string + { + $calls = ['->acceptJson()']; + + if ($signed) { + $calls[] = "->withHeaders(devnullHeaders('{$method}', '".self::SignedPrefix.$path."'".($body === null ? '' : ', $body').')) // see Authentication'; + } + + if ($body !== null) { + $calls[] = '->withBody($body)'; + } + + $url = "'".mb_ltrim($path, '/')."'"; + $request = $body === null && ! in_array($method, ['GET', 'DELETE'], true) + ? "->send('{$method}', {$url})" + : '->'.mb_strtolower($method)."({$url})"; + + $calls = [...$calls, $request, '->throw()', '->json();']; + + return implode("\n", [ + 'use Illuminate\Support\Facades\Http;', + '', + ...($body === null ? [] : ['$body = json_encode('.str_replace("'".self::Tomorrow."'", 'now()->addDay()->toIso8601String()', $this->php($body)).');', '']), + "\$response = Http::baseUrl('".self::BaseUrl."')", + ...array_map(fn (string $call): string => " {$call}", $calls), + ]); + } + + /** + * fetch, asking for JSON, its headers from devnullHeaders() when signing, which runs in Node.js, over the body it then + * sends as it is. fetch doesn't throw on an error status, so the example does, as Laravel's throw() does. + * + * @param array|null $body + */ + private function fetch(string $method, string $path, ?array $body, bool $signed, bool $answers): string + { + $options = []; + + if ($method !== 'GET') { + $options[] = "method: '{$method}',"; + } + + $signature = "devnullHeaders('{$method}', '".self::SignedPrefix.$path."'".($body === null ? '' : ', body').')'; + + $options = [ + ...$options, + 'headers: {', + ...($signed ? [" ...{$signature},"] : []), + " Accept: 'application/json',", + ...($body === null ? [] : [" 'Content-Type': 'application/json',"]), + '},', + ...($body === null ? [] : ['body,']), + ]; + + $call = "fetch('".self::BaseUrl.$path."', {\n".implode("\n", array_map(fn (string $option): string => " {$option}", $options))."\n});"; + + return implode("\n", [ + ...($signed ? ["import { devnullHeaders } from './devnull.mjs'; // see Authentication", ''] : []), + ...($body === null ? [] : ['const body = JSON.stringify('.str_replace("'".self::Tomorrow."'", "new Date(Date.now() + 86400000).toISOString().replace(/\\.\\d{3}Z\$/, '+00:00')", $this->javascript($body)).');', '']), + "const response = await {$call}", + 'if (!response.ok) throw new Error(await response.text());', + ...($answers ? ['const json = await response.json();'] : []), + ]); + } + + /** + * The path with its parameters filled in, and the query parameters a request can't go without. + * + * @param list $parameters + */ + private function path(string $path, array $parameters): string + { + $samples = self::QuerySamples[$path] ?? []; + $path = (string) preg_replace_callback('/\{(\w+)\}/', fn (array $match): string => self::Samples[$match[1]] ?? $match[0], $path); + + $query = []; + + foreach ($parameters as $parameter) { + if (is_array($parameter) && ($parameter['in'] ?? null) === 'query' && ($parameter['required'] ?? false) === true && is_string($parameter['name'] ?? null)) { + $query[Str::chopEnd($parameter['name'], '[]')] = $samples[$parameter['name']] ?? $this->sample($parameter); + } + } + + return $query === [] ? $path : $path.'?'.http_build_query($query); + } + + /** + * A body with every required field, as an example would fill it, or with every field when asked: a body that + * requires none still means something when it is sent empty, such as an org's name taken away. An object is filled + * with its own required fields, and left out when it has none: an empty object is never what a request means to + * send. A list of objects is a list of one. + * + * @param list $fields + * @return array|null + */ + private function body(array $fields, bool $everyField = false): ?array + { + $body = []; + + foreach ($fields as $field) { + if (! is_array($field) || ! $everyField && ($field['required'] ?? false) !== true || ! is_string($field['name'] ?? null)) { + continue; + } + + $children = $this->list($field['children'] ?? null); + $type = is_string($field['type'] ?? null) ? $field['type'] : ''; + + if ($children === []) { + $body[$field['name']] = $this->sample($field); + } elseif (($object = $this->body($children)) !== null) { + $body[$field['name']] = str_starts_with($type, 'array of ') ? [$object] : $object; + } + } + + return $body === [] ? null : $body; + } + + /** + * @param array $field + */ + private function sample(array $field): mixed + { + $name = is_string($field['name'] ?? null) ? $field['name'] : ''; + $type = is_string($field['type'] ?? null) ? Str::before($field['type'], ' | ') : 'string'; + $enum = $this->list($field['enum'] ?? null); + + return match (true) { + $enum !== [] => $enum[0], + isset(self::Samples[$name]) => self::Samples[$name], + $type === 'uuid' => self::Uuid, + $type === 'integer', $type === 'number' => 1, + $type === 'boolean' => true, + str_starts_with($type, 'array of ') => [$this->sample(['type' => mb_trim(Str::after($type, 'array of '), '()')])], + $type === 'array' => [], + $type === 'object' => new stdClass, + default => '…', + }; + } + + /** + * @param array $body + */ + private function json(array $body): string + { + return (string) json_encode($body, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE); + } + + /** + * A single-quoted shell word, a quote in it closing the word, escaped, and opening it again. + */ + private function shell(string $value): string + { + return "'".str_replace("'", "'\\''", $value)."'"; + } + + private function php(mixed $value): string + { + return match (true) { + is_array($value) && array_is_list($value) => '['.implode(', ', array_map($this->php(...), $value)).']', + is_array($value) => '['.implode(', ', array_map(fn (mixed $key, mixed $item): string => $this->php($key).' => '.$this->php($item), array_keys($value), $value)).']', + is_string($value) => "'".strtr($value, ['\\' => '\\\\', "'" => "\\'"])."'", + is_bool($value) => $value ? 'true' : 'false', + $value instanceof stdClass => '(object) []', + default => (string) json_encode($value), + }; + } + + private function javascript(mixed $value): string + { + return match (true) { + is_array($value) && array_is_list($value) => '['.implode(', ', array_map($this->javascript(...), $value)).']', + is_array($value) => '{ '.implode(', ', array_map(fn (mixed $key, mixed $item): string => $this->javascriptKey((string) $key).': '.$this->javascript($item), array_keys($value), $value)).' }', + is_string($value) => "'".strtr($value, ['\\' => '\\\\', "'" => "\\'", "\n" => '\n', "\r" => '\r'])."'", + is_bool($value) => $value ? 'true' : 'false', + $value instanceof stdClass => '{}', + default => (string) json_encode($value), + }; + } + + private function javascriptKey(string $key): string + { + return preg_match('/^[A-Za-z_$][\w$]*$/', $key) === 1 ? $key : $this->javascript($key); + } + + /** + * @return list + */ + private function list(mixed $value): array + { + return is_array($value) ? array_values($value) : []; + } +} diff --git a/app/Services/ApiGuideSnippets.php b/app/Services/ApiGuideSnippets.php new file mode 100644 index 0000000000..2365e022d5 --- /dev/null +++ b/app/Services/ApiGuideSnippets.php @@ -0,0 +1,84 @@ + + */ + public function for(ApiDocsSection $section): array + { + $snippets = match ($section) { + ApiDocsSection::Introduction => [ + 'firstRequest' => ['bash', 'curl '.ApiExamples::BaseUrl."/users/nunomaduro \\\n -H 'Accept: application/json'"], + ], + ApiDocsSection::Authentication => [ + 'keygen' => ['bash', "ssh-keygen -t ed25519 -f ~/.ssh/devnull -N ''"], + 'message' => ['text', "\n\n\n\n"], + ], + ApiDocsSection::Pagination => [ + 'page' => ['json', $this->page()], + ], + ApiDocsSection::Errors => [ + 'error' => ['json', <<<'JSON' + { + "message": "This commit isn't available.", + "code": "commit_unavailable" + } + JSON], + 'validation' => ['json', <<<'JSON' + { + "message": "The body field is required.", + "errors": { + "body": ["The body field is required."] + } + } + JSON], + ], + default => [], + }; + + return array_map(fn (array $snippet): array => [ + 'language' => $snippet[0], + 'html' => $this->highlighter->parse($snippet[1], $snippet[0]), + ], $snippets); + } + + private function page(): string + { + $url = ApiExamples::BaseUrl; + + return << 'api/v1', + + 'export_path' => 'resources/api/openapi.json', + + 'ui' => [ + 'title' => '/dev/null', + ], + + 'info' => [ + 'version' => '1', + 'description' => 'The JSON API the /dev/null apps use. Reading public profiles and commits needs nothing; acting for someone needs a request signed with an SSH key they approved as a device.', + ], + + 'servers' => [ + 'Production' => 'https://dev-null.sh/api/v1', + ], +]; diff --git a/resources/api/openapi.json b/resources/api/openapi.json new file mode 100644 index 0000000000..76e9bc6abc --- /dev/null +++ b/resources/api/openapi.json @@ -0,0 +1,16179 @@ +{ + "openapi": "3.1.2", + "info": { + "title": "/dev/null", + "version": "1", + "description": "The JSON API the /dev/null apps use. Reading public profiles and commits needs nothing; acting for someone needs a request signed with an SSH key they approved as a device." + }, + "servers": [ + { + "url": "https://dev-null.sh/api/v1", + "description": "Production" + } + ], + "tags": [ + { + "name": "Commits" + }, + { + "name": "Headlines" + }, + { + "name": "Issues" + }, + { + "name": "Me" + }, + { + "name": "Notifications" + }, + { + "name": "Organizations" + }, + { + "name": "Remotes" + }, + { + "name": "Scheduled commits" + }, + { + "name": "Search" + }, + { + "name": "Users" + } + ], + "paths": { + "/commits/{commit}": { + "get": { + "operationId": "api-commit.show", + "summary": "A signed request gets the commit as its page shows it to that user, with the commits it replies to above it, and\nwho else a reply to it can go to, as the web's Replying to lists them: everyone it was addressed to, besides its\nauthor and the user", + "tags": [ + "Commits" + ], + "parameters": [ + { + "name": "commit", + "in": "path", + "required": true, + "description": "The commit ID", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "`CommitResource`\n\n`CommitResource`", + "content": { + "application/json": { + "schema": { + "anyOf": [ + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/CommitResource" + } + }, + "required": [ + "data" + ] + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/CommitResource" + }, + "ancestors": { + "type": "array", + "items": { + "$ref": "#/components/schemas/CommitResource" + } + }, + "reply_participants": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "handle": { + "type": "string" + } + }, + "required": [ + "id", + "handle" + ] + } + } + }, + "required": [ + "data", + "ancestors", + "reply_participants" + ] + } + ] + } + } + } + }, + "404": { + "$ref": "#/components/responses/ModelNotFoundException" + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "403": { + "$ref": "#/components/responses/AuthorizationException" + }, + "401": { + "description": "The signature is stale or wrong, or the key that made it is not an approved device. Without one, the request reads as a guest.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + {}, + { + "devnullSignature": [] + } + ] + }, + "delete": { + "operationId": "api-commit.destroy", + "tags": [ + "Commits" + ], + "parameters": [ + { + "name": "commit", + "in": "path", + "required": true, + "description": "The commit ID", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "204": { + "description": "No content" + }, + "404": { + "$ref": "#/components/responses/ModelNotFoundException" + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "403": { + "$ref": "#/components/responses/AuthorizationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/commits/{commit}/related": { + "get": { + "operationId": "api-related-commit.index", + "tags": [ + "Commits" + ], + "parameters": [ + { + "name": "commit", + "in": "path", + "required": true, + "description": "The commit ID", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "Array of `CommitResource`", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/CommitResource" + } + } + }, + "required": [ + "data" + ] + } + } + } + }, + "404": { + "$ref": "#/components/responses/ModelNotFoundException" + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "403": { + "$ref": "#/components/responses/AuthorizationException" + }, + "401": { + "description": "The signature is stale or wrong, or the key that made it is not an approved device. Without one, the request reads as a guest.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + {}, + { + "devnullSignature": [] + } + ] + } + }, + "/commits": { + "post": { + "operationId": "api-commit.store", + "summary": "Answers with the new commit as its page shows it, with the commit it quotes and its poll, pending review unless\nthe user is an admin", + "tags": [ + "Commits" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateApiCommitRequest" + } + }, + "multipart/form-data": { + "schema": { + "type": "object", + "properties": { + "payload": { + "type": "string", + "format": "binary", + "contentMediaType": "application/json", + "description": "The request's fields, as the JSON body would send them, in a file part." + }, + "images": { + "type": "array", + "items": { + "type": "string", + "format": "binary", + "contentMediaType": "application/octet-stream", + "description": "Maximum file size: 10000 kilobytes." + } + } + }, + "required": [ + "payload", + "images" + ] + } + } + } + }, + "responses": { + "201": { + "description": "`CommitResource`", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/CommitResource" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/commits/{commit}/restoration": { + "post": { + "operationId": "api-commit-restoration.store", + "summary": "Undoes deleting the user's commit within the undo window, as Undo on the web does, and answers with the commit\nas its page shows it", + "tags": [ + "Commits" + ], + "parameters": [ + { + "name": "commit", + "in": "path", + "required": true, + "description": "The commit ID", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "`CommitResource`", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/CommitResource" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "404": { + "$ref": "#/components/responses/ModelNotFoundException" + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "403": { + "$ref": "#/components/responses/AuthorizationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/commits/{commit}/pin": { + "put": { + "operationId": "api-commit-pin.update", + "summary": "Pins the commit to the top of the user's profile, in place of the one pinned before, and answers with the commit\nas its page shows it, so the app gets the new is_pinned", + "tags": [ + "Commits" + ], + "parameters": [ + { + "name": "commit", + "in": "path", + "required": true, + "description": "The commit ID", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "`CommitResource`", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/CommitResource" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "404": { + "$ref": "#/components/responses/ModelNotFoundException" + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "403": { + "$ref": "#/components/responses/AuthorizationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + }, + "delete": { + "operationId": "api-commit-pin.destroy", + "tags": [ + "Commits" + ], + "parameters": [ + { + "name": "commit", + "in": "path", + "required": true, + "description": "The commit ID", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "`CommitResource`", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/CommitResource" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "404": { + "$ref": "#/components/responses/ModelNotFoundException" + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "403": { + "$ref": "#/components/responses/AuthorizationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/commits/{commit}/translation": { + "post": { + "operationId": "api-commit-translation.store", + "summary": "The commit in the language asked for, as Translate on the web shows it. A failed translation is a 503 the app\ncan retry, with the same message the web shows", + "tags": [ + "Commits" + ], + "parameters": [ + { + "name": "commit", + "in": "path", + "required": true, + "description": "The commit ID", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateApiCommitTranslationRequest" + } + } + } + }, + "responses": { + "200": { + "description": "", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "translation": { + "type": [ + "object", + "null" + ], + "properties": { + "language": { + "type": "string" + }, + "source_language": { + "type": [ + "string", + "null" + ] + }, + "source_name": { + "anyOf": [ + { + "type": "null" + }, + { + "type": "string" + }, + { + "type": "string", + "enum": [ + "Binary", + "Morse code" + ] + } + ] + }, + "available": { + "type": "boolean" + }, + "translated": { + "type": [ + "object", + "null" + ], + "properties": { + "body_segments": { + "anyOf": [ + { + "type": "array", + "prefixItems": [ + { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "text" + }, + "text": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "type", + "text" + ] + } + ], + "minItems": 1, + "maxItems": 1 + }, + { + "type": "array", + "items": { + "anyOf": [ + { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "block" + }, + "language": { + "type": [ + "string", + "null" + ] + }, + "filename": { + "type": [ + "string", + "null" + ] + }, + "html": { + "type": "string" + } + }, + "required": [ + "type", + "language", + "filename", + "html" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "code" + }, + "code": { + "type": "string" + } + }, + "required": [ + "type", + "code" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "text" + }, + "text": { + "type": "string" + } + }, + "required": [ + "type", + "text" + ] + } + ] + } + } + ] + }, + "preview_segments": { + "anyOf": [ + { + "type": "null" + }, + { + "type": "array", + "prefixItems": [ + { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "text" + }, + "text": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "type", + "text" + ] + } + ], + "minItems": 1, + "maxItems": 1 + }, + { + "type": "array", + "items": { + "anyOf": [ + { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "block" + }, + "language": { + "type": [ + "string", + "null" + ] + }, + "filename": { + "type": [ + "string", + "null" + ] + }, + "html": { + "type": "string" + } + }, + "required": [ + "type", + "language", + "filename", + "html" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "code" + }, + "code": { + "type": "string" + } + }, + "required": [ + "type", + "code" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "text" + }, + "text": { + "type": "string" + } + }, + "required": [ + "type", + "text" + ] + } + ] + } + } + ] + } + }, + "required": [ + "body_segments", + "preview_segments" + ] + } + }, + "required": [ + "language", + "source_language", + "source_name", + "available", + "translated" + ] + } + }, + "required": [ + "translation" + ] + } + } + } + }, + "503": { + "description": "", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "message": { + "type": "string", + "enum": [ + "The translation service returned an unsupported source language. Try again.", + "Could not translate this commit. Try again." + ] + } + }, + "required": [ + "message" + ] + } + } + } + }, + "404": { + "$ref": "#/components/responses/ModelNotFoundException" + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "403": { + "$ref": "#/components/responses/AuthorizationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/commits/preview": { + "post": { + "operationId": "api-commit-preview.store", + "summary": "Shows a draft as the commit it would become, as the web's composer previews it: the body as it would be kept, the\nsegments the app draws it from, the excerpt a list would fold it to, and where it mentions someone. Nothing is\nkept, so previews don't count towards the commits a user may make a minute", + "tags": [ + "Commits" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateApiCommitPreviewRequest" + } + } + } + }, + "responses": { + "200": { + "description": "", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "body": { + "type": "string" + }, + "body_segments": { + "anyOf": [ + { + "type": "array", + "prefixItems": [ + { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "text" + }, + "text": { + "type": "string" + } + }, + "required": [ + "type", + "text" + ] + } + ], + "minItems": 1, + "maxItems": 1 + }, + { + "type": "array", + "items": { + "anyOf": [ + { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "block" + }, + "language": { + "type": [ + "string", + "null" + ] + }, + "filename": { + "type": [ + "string", + "null" + ] + }, + "html": { + "type": "string" + } + }, + "required": [ + "type", + "language", + "filename", + "html" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "code" + }, + "code": { + "type": "string" + } + }, + "required": [ + "type", + "code" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "text" + }, + "text": { + "type": "string" + } + }, + "required": [ + "type", + "text" + ] + } + ] + } + } + ] + }, + "preview_segments": { + "anyOf": [ + { + "type": "null" + }, + { + "type": "array", + "prefixItems": [ + { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "text" + }, + "text": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "type", + "text" + ] + } + ], + "minItems": 1, + "maxItems": 1 + }, + { + "type": "array", + "items": { + "anyOf": [ + { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "block" + }, + "language": { + "type": [ + "string", + "null" + ] + }, + "filename": { + "type": [ + "string", + "null" + ] + }, + "html": { + "type": "string" + } + }, + "required": [ + "type", + "language", + "filename", + "html" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "code" + }, + "code": { + "type": "string" + } + }, + "required": [ + "type", + "code" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "text" + }, + "text": { + "type": "string" + } + }, + "required": [ + "type", + "text" + ] + } + ] + } + } + ] + }, + "mentions": { + "type": "array", + "items": { + "type": "object", + "properties": { + "handle": { + "type": "string" + }, + "offset": { + "type": "integer" + }, + "length": { + "type": "integer" + }, + "kind": { + "type": "string", + "enum": [ + "organization", + "user" + ] + } + }, + "required": [ + "handle", + "offset", + "length", + "kind" + ] + } + } + }, + "required": [ + "body", + "body_segments", + "preview_segments", + "mentions" + ] + } + }, + "required": [ + "data" + ] + } + } + } + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/commits/{commit}/replies": { + "get": { + "operationId": "api-commit-reply.index", + "tags": [ + "Commits" + ], + "parameters": [ + { + "name": "commit", + "in": "path", + "required": true, + "description": "The commit ID", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "newest", + "in": "query", + "schema": { + "type": "boolean" + } + } + ], + "responses": { + "200": { + "description": "Paginated set of `CommitResource`", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/CommitResource" + } + }, + "links": { + "type": "object", + "properties": { + "first": { + "type": [ + "string", + "null" + ] + }, + "last": { + "type": [ + "string", + "null" + ] + }, + "prev": { + "type": [ + "string", + "null" + ] + }, + "next": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "first", + "last", + "prev", + "next" + ] + }, + "meta": { + "type": "object", + "properties": { + "path": { + "type": [ + "string", + "null" + ], + "description": "Base path for paginator generated URLs." + }, + "per_page": { + "type": "integer", + "description": "Number of items shown per page.", + "minimum": 0 + }, + "next_cursor": { + "type": [ + "string", + "null" + ], + "description": "The \"cursor\" that points to the next set of items." + }, + "prev_cursor": { + "type": [ + "string", + "null" + ], + "description": "The \"cursor\" that points to the previous set of items." + } + }, + "required": [ + "path", + "per_page", + "next_cursor", + "prev_cursor" + ] + } + }, + "required": [ + "data", + "links", + "meta" + ] + } + } + } + }, + "404": { + "$ref": "#/components/responses/ModelNotFoundException" + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "403": { + "$ref": "#/components/responses/AuthorizationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/commits/{commit}/reports": { + "post": { + "operationId": "api-commit-report.store", + "summary": "Reports are private, so there is nothing to answer with. Reporting a commit again keeps the first report", + "tags": [ + "Commits" + ], + "parameters": [ + { + "name": "commit", + "in": "path", + "required": true, + "description": "The commit ID", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateApiCommitReportRequest" + } + }, + "multipart/form-data": { + "schema": { + "type": "object", + "properties": { + "payload": { + "type": "string", + "format": "binary", + "contentMediaType": "application/json", + "description": "The request's fields, as the JSON body would send them, in a file part." + }, + "images": { + "type": "array", + "items": { + "type": "string", + "format": "binary", + "contentMediaType": "application/octet-stream", + "description": "Maximum file size: 10000 kilobytes." + } + } + }, + "required": [ + "payload", + "images" + ] + } + } + } + }, + "responses": { + "204": { + "description": "No content" + }, + "404": { + "$ref": "#/components/responses/ModelNotFoundException" + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/commits/{commit}/pasteis": { + "post": { + "operationId": "api-commit-pastel.store", + "summary": "Gives the commit one pastel from the user's daily allowance, as the web's pastel button does. It answers with the\ncommit as its page shows it, so the app gets the new pasteis_count, with how many past\u00e9is the user has left\ntoday and how many its author has been given in all. With none left, it is a pasteis_exhausted error", + "tags": [ + "Commits" + ], + "parameters": [ + { + "name": "commit", + "in": "path", + "required": true, + "description": "The commit ID", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "`CommitResource`", + "content": { + "application/json": { + "schema": { + "anyOf": [ + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/CommitResource" + }, + "pasteis_remaining": { + "type": "integer" + }, + "pasteis_resets_at": { + "type": "string" + }, + "author_pasteis_received": { + "type": [ + "integer", + "null" + ] + } + }, + "required": [ + "data", + "pasteis_remaining", + "pasteis_resets_at", + "author_pasteis_received" + ] + }, + { + "type": "string" + } + ] + } + } + } + }, + "404": { + "$ref": "#/components/responses/ModelNotFoundException" + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "403": { + "$ref": "#/components/responses/AuthorizationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/commits/{commit}/poll/votes": { + "post": { + "operationId": "api-commit-poll-vote.store", + "summary": "Votes on the commit's poll, as the web's Vote button does. It answers with the commit as its page shows it, so\nthe app gets the poll with its results, which show once the user voted", + "tags": [ + "Commits" + ], + "parameters": [ + { + "name": "commit", + "in": "path", + "required": true, + "description": "The commit ID", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateApiCommitPollVoteRequest" + } + } + } + }, + "responses": { + "200": { + "description": "`CommitResource`", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/CommitResource" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "404": { + "$ref": "#/components/responses/ModelNotFoundException" + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "403": { + "$ref": "#/components/responses/AuthorizationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/commits/{commit}/stars": { + "get": { + "operationId": "api-commit-star.index", + "summary": "Who starred the commit, newest first, 20 a page as on the web. People across a block are left out", + "tags": [ + "Commits" + ], + "parameters": [ + { + "name": "commit", + "in": "path", + "required": true, + "description": "The commit ID", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "Paginated set of `UserResource`", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/UserResource" + } + }, + "links": { + "type": "object", + "properties": { + "first": { + "type": [ + "string", + "null" + ] + }, + "last": { + "type": [ + "string", + "null" + ] + }, + "prev": { + "type": [ + "string", + "null" + ] + }, + "next": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "first", + "last", + "prev", + "next" + ] + }, + "meta": { + "type": "object", + "properties": { + "path": { + "type": [ + "string", + "null" + ], + "description": "Base path for paginator generated URLs." + }, + "per_page": { + "type": "integer", + "description": "Number of items shown per page.", + "minimum": 0 + }, + "next_cursor": { + "type": [ + "string", + "null" + ], + "description": "The \"cursor\" that points to the next set of items." + }, + "prev_cursor": { + "type": [ + "string", + "null" + ], + "description": "The \"cursor\" that points to the previous set of items." + } + }, + "required": [ + "path", + "per_page", + "next_cursor", + "prev_cursor" + ] + } + }, + "required": [ + "data", + "links", + "meta" + ] + } + } + } + }, + "404": { + "$ref": "#/components/responses/ModelNotFoundException" + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "403": { + "$ref": "#/components/responses/AuthorizationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/commits/{commit}/star": { + "post": { + "operationId": "api-commit-star.store", + "summary": "Answers with the commit as its page shows it, so the app gets the new stars_count and starred", + "tags": [ + "Commits" + ], + "parameters": [ + { + "name": "commit", + "in": "path", + "required": true, + "description": "The commit ID", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "`CommitResource`", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/CommitResource" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "404": { + "$ref": "#/components/responses/ModelNotFoundException" + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "403": { + "$ref": "#/components/responses/AuthorizationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + }, + "delete": { + "operationId": "api-commit-star.destroy", + "tags": [ + "Commits" + ], + "parameters": [ + { + "name": "commit", + "in": "path", + "required": true, + "description": "The commit ID", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "`CommitResource`", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/CommitResource" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "404": { + "$ref": "#/components/responses/ModelNotFoundException" + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "403": { + "$ref": "#/components/responses/AuthorizationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/headlines": { + "get": { + "operationId": "api-headline.index", + "tags": [ + "Headlines" + ], + "responses": { + "200": { + "description": "", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": {} + } + }, + "required": [ + "data" + ] + } + } + } + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/headlines/{headline}": { + "get": { + "operationId": "api-headline.show", + "tags": [ + "Headlines" + ], + "parameters": [ + { + "name": "headline", + "in": "path", + "required": true, + "description": "The headline ID", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "Array of `CommitResource`", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/CommitResource" + } + }, + "name": { + "type": "string" + }, + "summary": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "data", + "name", + "summary" + ] + } + } + } + }, + "404": { + "$ref": "#/components/responses/ModelNotFoundException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/issues": { + "post": { + "operationId": "api-issue.store", + "summary": "Opens a /feature or /bug issue as the web does. When GitHub fails, the app keeps the draft", + "tags": [ + "Issues" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateApiIssueRequest" + } + } + } + }, + "responses": { + "201": { + "description": "", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "number": { + "type": "integer" + }, + "url": { + "type": "string" + } + }, + "required": [ + "number", + "url" + ] + } + } + } + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/me": { + "get": { + "operationId": "api-current-user.show", + "summary": "The signed-in user, with the unread count the web shows on Notifications", + "tags": [ + "Me" + ], + "responses": { + "200": { + "description": "`CurrentUserResource`", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/CurrentUserResource" + }, + "unread_notifications_count": { + "type": "integer" + } + }, + "required": [ + "data", + "unread_notifications_count" + ] + } + } + } + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + }, + "delete": { + "operationId": "api-current-user.destroy", + "summary": "Deletes the account the way the web does, and its devices with it, so the key that signed the request stops working", + "tags": [ + "Me" + ], + "responses": { + "204": { + "description": "No content" + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/me/pasteis-mode": { + "put": { + "operationId": "api-user-pasteis-mode.update", + "summary": "Turns past\u00e9is mode on or off, as the switch in the web's settings does, and answers as GET /api/v1/me does", + "tags": [ + "Me" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateApiUserPasteisModeRequest" + } + } + } + }, + "responses": { + "200": { + "description": "`CurrentUserResource`", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/CurrentUserResource" + }, + "unread_notifications_count": { + "type": "integer" + } + }, + "required": [ + "data", + "unread_notifications_count" + ] + } + } + } + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/me/terms": { + "put": { + "operationId": "api-user-terms.update", + "summary": "Records that the person ticked the box for the terms and privacy policy in the app, and answers as GET /api/v1/me does", + "tags": [ + "Me" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateApiUserTermsRequest" + } + } + } + }, + "responses": { + "200": { + "description": "`CurrentUserResource`", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/CurrentUserResource" + }, + "unread_notifications_count": { + "type": "integer" + } + }, + "required": [ + "data", + "unread_notifications_count" + ] + } + } + } + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/me/github": { + "put": { + "operationId": "api-user-profile.update", + "summary": "Mirrors the user's GitHub profile again, as Sync from GitHub does on the web, and answers as GET /api/v1/me does", + "tags": [ + "Me" + ], + "responses": { + "200": { + "description": "`CurrentUserResource`", + "content": { + "application/json": { + "schema": { + "anyOf": [ + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/CurrentUserResource" + }, + "unread_notifications_count": { + "type": "integer" + } + }, + "required": [ + "data", + "unread_notifications_count" + ] + }, + { + "type": "string" + } + ] + } + } + } + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/me/lane": { + "put": { + "operationId": "api-user-lane.update", + "summary": "Saves the user's color, as Save color does on the web, and answers as GET /api/v1/me does", + "tags": [ + "Me" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateApiUserLaneRequest" + } + } + } + }, + "responses": { + "200": { + "description": "`CurrentUserResource`", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/CurrentUserResource" + }, + "unread_notifications_count": { + "type": "integer" + } + }, + "required": [ + "data", + "unread_notifications_count" + ] + } + } + } + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/me/live": { + "put": { + "operationId": "api-user-live.update", + "summary": "Marks the user live on their stream for a few hours, as Go live does on the web, and answers as GET /api/v1/me\ndoes", + "tags": [ + "Me" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateApiUserLiveRequest" + } + } + } + }, + "responses": { + "200": { + "description": "`CurrentUserResource`", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/CurrentUserResource" + }, + "unread_notifications_count": { + "type": "integer" + } + }, + "required": [ + "data", + "unread_notifications_count" + ] + } + } + } + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + }, + "delete": { + "operationId": "api-user-live.destroy", + "summary": "Ends the user's stream early, as End stream does on the web, and answers as GET /api/v1/me does", + "tags": [ + "Me" + ], + "responses": { + "200": { + "description": "`CurrentUserResource`", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/CurrentUserResource" + }, + "unread_notifications_count": { + "type": "integer" + } + }, + "required": [ + "data", + "unread_notifications_count" + ] + } + } + } + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/me/live-following": { + "get": { + "operationId": "api-live-following.index", + "summary": "A few of the people the user follows who are live right now, as the web's Live now aside shows them", + "tags": [ + "Me" + ], + "responses": { + "200": { + "description": "Array of `UserResource`", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/UserResource" + } + } + }, + "required": [ + "data" + ] + } + } + } + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/me/settings": { + "get": { + "operationId": "api-user-settings.show", + "summary": "What the web's settings show only the user: their timezone and the language commits are translated into, `null`\nto follow the device, whether commits are translated automatically, the languages they may pick from, whether\nthe web shows them its admin pages, which the app only links to, and what they want pushed to their phones", + "tags": [ + "Me" + ], + "responses": { + "200": { + "description": "", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "object", + "properties": { + "timezone": { + "type": "string" + }, + "show_local_time": { + "type": "string" + }, + "translation_language": { + "type": "string" + }, + "automatic_translation": { + "type": "string" + }, + "translation_languages": { + "type": "array", + "items": { + "type": "object", + "properties": { + "code": { + "type": "string" + }, + "name": { + "type": "string" + }, + "native_name": { + "type": "string" + } + }, + "required": [ + "code", + "name", + "native_name" + ] + } + }, + "is_admin": { + "type": "boolean" + }, + "push": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + }, + "required": [ + "timezone", + "show_local_time", + "translation_language", + "automatic_translation", + "translation_languages", + "is_admin", + "push" + ] + } + }, + "required": [ + "data" + ] + } + } + } + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/me/timezone": { + "put": { + "operationId": "api-user-timezone.update", + "summary": "Saves the timezone the web shows times in, as Settings does on the web, and answers as GET /api/v1/me does", + "tags": [ + "Me" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateApiUserTimezoneRequest" + } + } + } + }, + "responses": { + "200": { + "description": "`CurrentUserResource`", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/CurrentUserResource" + }, + "unread_notifications_count": { + "type": "integer" + } + }, + "required": [ + "data", + "unread_notifications_count" + ] + } + } + } + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/me/automatic-translation": { + "put": { + "operationId": "api-user-automatic-translation.update", + "summary": "Turns automatic translation on or off, as Settings does on the web, and answers as GET /api/v1/me does", + "tags": [ + "Me" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateApiUserAutomaticTranslationRequest" + } + } + } + }, + "responses": { + "200": { + "description": "`CurrentUserResource`", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/CurrentUserResource" + }, + "unread_notifications_count": { + "type": "integer" + } + }, + "required": [ + "data", + "unread_notifications_count" + ] + } + } + } + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/me/translation-language": { + "put": { + "operationId": "api-user-translation-language.update", + "summary": "Saves the language commits are translated into, as Settings does on the web, and answers as GET /api/v1/me does", + "tags": [ + "Me" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateApiUserTranslationLanguageRequest" + } + } + } + }, + "responses": { + "200": { + "description": "`CurrentUserResource`", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/CurrentUserResource" + }, + "unread_notifications_count": { + "type": "integer" + } + }, + "required": [ + "data", + "unread_notifications_count" + ] + } + } + } + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/me/devices": { + "get": { + "operationId": "api-device.index", + "summary": "The devices that may sign requests as the user, newest approval first, as the web's Devices page lists them", + "tags": [ + "Me" + ], + "responses": { + "200": { + "description": "Array of `DeviceResource`", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/DeviceResource" + } + } + }, + "required": [ + "data" + ] + } + } + } + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/me/devices/{device}": { + "delete": { + "operationId": "api-device.destroy", + "summary": "Revokes the device. Revoking the one that signed the request signs the app out on it", + "tags": [ + "Me" + ], + "parameters": [ + { + "name": "device", + "in": "path", + "required": true, + "description": "The device ID", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "204": { + "description": "No content" + }, + "404": { + "$ref": "#/components/responses/ModelNotFoundException" + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "403": { + "$ref": "#/components/responses/AuthorizationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/me/push-token": { + "put": { + "operationId": "api-device-push-token.update", + "summary": "Saves the token pushes reach the phone that signed the request with, replacing the one it sent before", + "tags": [ + "Me" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateApiDevicePushTokenRequest" + } + } + } + }, + "responses": { + "204": { + "description": "No content" + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + }, + "delete": { + "operationId": "api-device-push-token.destroy", + "summary": "Stops pushing to the phone that signed the request, as when the app signs out or notifications are turned off", + "tags": [ + "Me" + ], + "responses": { + "204": { + "description": "No content" + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/me/push-preferences": { + "put": { + "operationId": "api-user-push-preferences.update", + "summary": "Saves what the user wants pushed to their phones, and answers with all of it, as GET /api/v1/me/settings shows\nit under `push`", + "tags": [ + "Me" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateApiUserPushPreferencesRequest" + } + } + } + }, + "responses": { + "200": { + "description": "", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + }, + "required": [ + "data" + ] + } + } + } + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/me/remotes": { + "put": { + "operationId": "api-user-remotes.update", + "summary": "Turns Remotes on or off, as the switch in the web's settings does, and answers as GET /api/v1/me does. While\nthey are off, nobody can message the user and the conversations wait for them to come back", + "tags": [ + "Me" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateApiUserRemotesRequest" + } + } + } + }, + "responses": { + "200": { + "description": "`CurrentUserResource`", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/CurrentUserResource" + }, + "unread_notifications_count": { + "type": "integer" + } + }, + "required": [ + "data", + "unread_notifications_count" + ] + } + } + } + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/me/remote-preferences": { + "put": { + "operationId": "api-user-remote-preferences.update", + "summary": "Saves who can push to the user and whether they share pulls, as the settings menu on the web's Remotes page\ndoes, and answers as GET /api/v1/me does", + "tags": [ + "Me" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateApiUserRemotePreferencesRequest" + } + } + } + }, + "responses": { + "200": { + "description": "`CurrentUserResource`", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/CurrentUserResource" + }, + "unread_notifications_count": { + "type": "integer" + } + }, + "required": [ + "data", + "unread_notifications_count" + ] + } + } + } + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "403": { + "$ref": "#/components/responses/AuthorizationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/log/{log}": { + "get": { + "operationId": "api-log.show", + "summary": "Following, Latest or Trending, as the web shows it, 20 commits a page. With ?since=, it counts the commits newer\nthan that one, the way the web does: none on Trending, which is ranked rather than newest first. An empty\nFollowing log suggests a few commits, as on the web", + "tags": [ + "Me" + ], + "parameters": [ + { + "name": "log", + "in": "path", + "required": true, + "description": "The log ID", + "schema": { + "$ref": "#/components/schemas/Log" + } + }, + { + "name": "since", + "in": "query", + "schema": { + "type": [ + "string", + "null" + ], + "format": "uuid" + } + }, + { + "name": "through", + "in": "query", + "description": "The oldest loaded commits, oldest first, so the range holds even when the oldest is hidden or gone.", + "schema": { + "type": [ + "string", + "null" + ], + "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}(,[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}){0,19}$" + } + }, + { + "name": "pending[]", + "in": "query", + "required": true, + "schema": { + "type": "array", + "items": { + "type": "string", + "format": "uuid" + }, + "maxItems": 100, + "uniqueItems": true + } + }, + { + "name": "arrived[]", + "in": "query", + "required": true, + "schema": { + "type": "array", + "items": { + "type": "string", + "format": "uuid" + }, + "maxItems": 100, + "uniqueItems": true + } + }, + { + "name": "everything", + "in": "query", + "schema": { + "type": "boolean" + } + } + ], + "responses": { + "200": { + "description": "Paginated set of `CommitResource`", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/CommitResource" + } + }, + "links": { + "type": "object", + "properties": { + "first": { + "type": [ + "string", + "null" + ] + }, + "last": { + "type": [ + "string", + "null" + ] + }, + "prev": { + "type": [ + "string", + "null" + ] + }, + "next": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "first", + "last", + "prev", + "next" + ] + }, + "meta": { + "type": "object", + "properties": { + "path": { + "type": [ + "string", + "null" + ], + "description": "Base path for paginator generated URLs." + }, + "per_page": { + "type": "integer", + "description": "Number of items shown per page.", + "minimum": 0 + }, + "next_cursor": { + "type": [ + "string", + "null" + ], + "description": "The \"cursor\" that points to the next set of items." + }, + "prev_cursor": { + "type": [ + "string", + "null" + ], + "description": "The \"cursor\" that points to the previous set of items." + } + }, + "required": [ + "path", + "per_page", + "next_cursor", + "prev_cursor" + ] + }, + "log": { + "anyOf": [ + { + "$ref": "#/components/schemas/Log" + }, + {} + ] + }, + "is_ranked": { + "anyOf": [ + { + "type": "boolean" + }, + {} + ] + }, + "suggestions": { + "type": "array", + "items": { + "$ref": "#/components/schemas/CommitResource" + } + } + }, + "required": [ + "data", + "links", + "meta", + "log", + "is_ranked", + "suggestions" + ] + } + } + } + }, + "404": { + "$ref": "#/components/responses/ModelNotFoundException" + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/starred": { + "get": { + "operationId": "api-starred.index", + "tags": [ + "Me" + ], + "responses": { + "200": { + "description": "Paginated set of `CommitResource`", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/CommitResource" + } + }, + "links": { + "type": "object", + "properties": { + "first": { + "type": [ + "string", + "null" + ] + }, + "last": { + "type": [ + "string", + "null" + ] + }, + "prev": { + "type": [ + "string", + "null" + ] + }, + "next": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "first", + "last", + "prev", + "next" + ] + }, + "meta": { + "type": "object", + "properties": { + "path": { + "type": [ + "string", + "null" + ], + "description": "Base path for paginator generated URLs." + }, + "per_page": { + "type": "integer", + "description": "Number of items shown per page.", + "minimum": 0 + }, + "next_cursor": { + "type": [ + "string", + "null" + ], + "description": "The \"cursor\" that points to the next set of items." + }, + "prev_cursor": { + "type": [ + "string", + "null" + ], + "description": "The \"cursor\" that points to the previous set of items." + } + }, + "required": [ + "path", + "per_page", + "next_cursor", + "prev_cursor" + ] + } + }, + "required": [ + "data", + "links", + "meta" + ] + } + } + } + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/me/suggested-users": { + "get": { + "operationId": "api-suggested-user.index", + "summary": "Who to follow, as the web suggests them: three people to show and three spares to fill the place of one\ndismissed, each with why they are suggested and whether they follow the user. Each round is the next page of\nthe day's picks, as the web's refresh button shows. Beside a profile or a commit, the people that developer\nfollows or the thread's participants come first, as the web suggests them there. Nobody suggested is followed\nyet, which each one says, as in any other list of people", + "tags": [ + "Me" + ], + "parameters": [ + { + "name": "round", + "in": "query", + "schema": { + "type": [ + "integer", + "null" + ], + "minimum": 0 + } + }, + { + "name": "handle", + "in": "query", + "schema": { + "type": [ + "string", + "null" + ] + } + }, + { + "name": "commit_id", + "in": "query", + "schema": { + "type": [ + "string", + "null" + ], + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "Array of `UserResource`", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/UserResource" + } + } + }, + "required": [ + "data" + ] + } + } + } + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/me/muted": { + "get": { + "operationId": "api-user-mute.index", + "summary": "The people the user mutes, last muted first, as Settings \u2192 Safety lists them, 20 a page", + "tags": [ + "Me" + ], + "responses": { + "200": { + "description": "Paginated set of `UserResource`", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/UserResource" + } + }, + "links": { + "type": "object", + "properties": { + "first": { + "type": [ + "string", + "null" + ] + }, + "last": { + "type": [ + "string", + "null" + ] + }, + "prev": { + "type": [ + "string", + "null" + ] + }, + "next": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "first", + "last", + "prev", + "next" + ] + }, + "meta": { + "type": "object", + "properties": { + "path": { + "type": [ + "string", + "null" + ], + "description": "Base path for paginator generated URLs." + }, + "per_page": { + "type": "integer", + "description": "Number of items shown per page.", + "minimum": 0 + }, + "next_cursor": { + "type": [ + "string", + "null" + ], + "description": "The \"cursor\" that points to the next set of items." + }, + "prev_cursor": { + "type": [ + "string", + "null" + ], + "description": "The \"cursor\" that points to the previous set of items." + } + }, + "required": [ + "path", + "per_page", + "next_cursor", + "prev_cursor" + ] + } + }, + "required": [ + "data", + "links", + "meta" + ] + } + } + } + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/me/blocked": { + "get": { + "operationId": "api-user-block.index", + "summary": "The people the user blocks, last blocked first, as Settings \u2192 Safety lists them, 20 a page", + "tags": [ + "Me" + ], + "responses": { + "200": { + "description": "Paginated set of `UserResource`", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/UserResource" + } + }, + "links": { + "type": "object", + "properties": { + "first": { + "type": [ + "string", + "null" + ] + }, + "last": { + "type": [ + "string", + "null" + ] + }, + "prev": { + "type": [ + "string", + "null" + ] + }, + "next": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "first", + "last", + "prev", + "next" + ] + }, + "meta": { + "type": "object", + "properties": { + "path": { + "type": [ + "string", + "null" + ], + "description": "Base path for paginator generated URLs." + }, + "per_page": { + "type": "integer", + "description": "Number of items shown per page.", + "minimum": 0 + }, + "next_cursor": { + "type": [ + "string", + "null" + ], + "description": "The \"cursor\" that points to the next set of items." + }, + "prev_cursor": { + "type": [ + "string", + "null" + ], + "description": "The \"cursor\" that points to the previous set of items." + } + }, + "required": [ + "path", + "per_page", + "next_cursor", + "prev_cursor" + ] + } + }, + "required": [ + "data", + "links", + "meta" + ] + } + } + } + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/notifications": { + "get": { + "operationId": "api-notification.index", + "summary": "The notifications grouped and filtered by ?type= like the web does it. As on the web, listing them marks every\nnotification as read, whatever the filter, and read_at says when, so the ones read since then are the new ones.\nA commit comes with its author and the commit it replies to, when the user may see it", + "tags": [ + "Notifications" + ], + "parameters": [ + { + "name": "type", + "in": "query", + "schema": { + "type": [ + "string", + "null" + ], + "pattern": "^(?:all|none|(?:replies|quotes|stars|mentions|follows|moderation)(?:,(?:replies|quotes|stars|mentions|follows|moderation))*)$" + } + }, + { + "name": "through", + "in": "query", + "schema": { + "type": [ + "string", + "null" + ], + "format": "date-time" + } + } + ], + "responses": { + "200": { + "description": "Paginated set of `NotificationResource`", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/NotificationResource" + } + }, + "links": { + "type": "object", + "properties": { + "first": { + "type": [ + "string", + "null" + ] + }, + "last": { + "type": [ + "string", + "null" + ] + }, + "prev": { + "type": [ + "string", + "null" + ] + }, + "next": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "first", + "last", + "prev", + "next" + ] + }, + "meta": { + "type": "object", + "properties": { + "path": { + "type": [ + "string", + "null" + ], + "description": "Base path for paginator generated URLs." + }, + "per_page": { + "type": "integer", + "description": "Number of items shown per page.", + "minimum": 0 + }, + "next_cursor": { + "type": [ + "string", + "null" + ], + "description": "The \"cursor\" that points to the next set of items." + }, + "prev_cursor": { + "type": [ + "string", + "null" + ], + "description": "The \"cursor\" that points to the previous set of items." + } + }, + "required": [ + "path", + "per_page", + "next_cursor", + "prev_cursor" + ] + }, + "filters": { + "type": "object", + "properties": { + "type": { + "type": "string" + } + }, + "required": [ + "type" + ] + }, + "read_at": { + "type": "string" + } + }, + "required": [ + "data", + "links", + "meta", + "filters", + "read_at" + ] + } + } + } + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/notifications/{notification}/group": { + "get": { + "operationId": "api-notification-group.show", + "summary": "Every notification in the group the given one belongs to, newest first and filtered by ?type=, as the web\nexpands a group. Listing them marks nothing as read", + "tags": [ + "Notifications" + ], + "parameters": [ + { + "name": "notification", + "in": "path", + "required": true, + "description": "The notification ID", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "type", + "in": "query", + "schema": { + "type": [ + "string", + "null" + ], + "pattern": "^(?:all|none|(?:replies|quotes|stars|mentions|follows|moderation)(?:,(?:replies|quotes|stars|mentions|follows|moderation))*)$" + } + } + ], + "responses": { + "200": { + "description": "Paginated set of `NotificationResource`", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/NotificationResource" + } + }, + "links": { + "type": "object", + "properties": { + "first": { + "type": [ + "string", + "null" + ] + }, + "last": { + "type": [ + "string", + "null" + ] + }, + "prev": { + "type": [ + "string", + "null" + ] + }, + "next": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "first", + "last", + "prev", + "next" + ] + }, + "meta": { + "type": "object", + "properties": { + "path": { + "type": [ + "string", + "null" + ], + "description": "Base path for paginator generated URLs." + }, + "per_page": { + "type": "integer", + "description": "Number of items shown per page.", + "minimum": 0 + }, + "next_cursor": { + "type": [ + "string", + "null" + ], + "description": "The \"cursor\" that points to the next set of items." + }, + "prev_cursor": { + "type": [ + "string", + "null" + ], + "description": "The \"cursor\" that points to the previous set of items." + } + }, + "required": [ + "path", + "per_page", + "next_cursor", + "prev_cursor" + ] + } + }, + "required": [ + "data", + "links", + "meta" + ] + } + } + } + }, + "404": { + "$ref": "#/components/responses/ModelNotFoundException" + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "403": { + "$ref": "#/components/responses/AuthorizationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/organizations/{handle}": { + "get": { + "operationId": "api-organization.show", + "summary": "Organizations share the \"@handle\" pages with users, so the app asks for one when no user has the handle. A\nsigned request also gets whether its user follows it, whether they can claim it, as anyone signed in can before\nit has an admin, and its settings on the web for its members, as its page on the web links them", + "tags": [ + "Organizations" + ], + "parameters": [ + { + "name": "handle", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "`OrganizationResource`", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/OrganizationResource" + }, + "is_following": { + "type": "boolean" + }, + "can_claim": { + "type": "boolean" + }, + "settings_url": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "data", + "is_following", + "can_claim", + "settings_url" + ] + } + } + } + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "403": { + "$ref": "#/components/responses/AuthorizationException" + }, + "401": { + "description": "The signature is stale or wrong, or the key that made it is not an approved device. Without one, the request reads as a guest.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + {}, + { + "devnullSignature": [] + } + ] + } + }, + "/organizations/{handle}/commits": { + "get": { + "operationId": "api-organization-commit.index", + "summary": "A signed request gets the organization's Commits tab as the web shows it to that user", + "tags": [ + "Organizations" + ], + "parameters": [ + { + "name": "handle", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Paginated set of `CommitResource`", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/CommitResource" + } + }, + "links": { + "type": "object", + "properties": { + "first": { + "type": [ + "string", + "null" + ] + }, + "last": { + "type": [ + "string", + "null" + ] + }, + "prev": { + "type": [ + "string", + "null" + ] + }, + "next": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "first", + "last", + "prev", + "next" + ] + }, + "meta": { + "type": "object", + "properties": { + "path": { + "type": [ + "string", + "null" + ], + "description": "Base path for paginator generated URLs." + }, + "per_page": { + "type": "integer", + "description": "Number of items shown per page.", + "minimum": 0 + }, + "next_cursor": { + "type": [ + "string", + "null" + ], + "description": "The \"cursor\" that points to the next set of items." + }, + "prev_cursor": { + "type": [ + "string", + "null" + ], + "description": "The \"cursor\" that points to the previous set of items." + } + }, + "required": [ + "path", + "per_page", + "next_cursor", + "prev_cursor" + ] + } + }, + "required": [ + "data", + "links", + "meta" + ] + } + } + } + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "403": { + "$ref": "#/components/responses/AuthorizationException" + }, + "401": { + "description": "The signature is stale or wrong, or the key that made it is not an approved device. Without one, the request reads as a guest.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + {}, + { + "devnullSignature": [] + } + ] + } + }, + "/organizations/{handle}/mentions": { + "get": { + "operationId": "api-organization-mention.index", + "summary": "A signed request gets the organization's Mentions tab as the web shows it to that user", + "tags": [ + "Organizations" + ], + "parameters": [ + { + "name": "handle", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Paginated set of `CommitResource`", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/CommitResource" + } + }, + "links": { + "type": "object", + "properties": { + "first": { + "type": [ + "string", + "null" + ] + }, + "last": { + "type": [ + "string", + "null" + ] + }, + "prev": { + "type": [ + "string", + "null" + ] + }, + "next": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "first", + "last", + "prev", + "next" + ] + }, + "meta": { + "type": "object", + "properties": { + "path": { + "type": [ + "string", + "null" + ], + "description": "Base path for paginator generated URLs." + }, + "per_page": { + "type": "integer", + "description": "Number of items shown per page.", + "minimum": 0 + }, + "next_cursor": { + "type": [ + "string", + "null" + ], + "description": "The \"cursor\" that points to the next set of items." + }, + "prev_cursor": { + "type": [ + "string", + "null" + ], + "description": "The \"cursor\" that points to the previous set of items." + } + }, + "required": [ + "path", + "per_page", + "next_cursor", + "prev_cursor" + ] + } + }, + "required": [ + "data", + "links", + "meta" + ] + } + } + } + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "403": { + "$ref": "#/components/responses/AuthorizationException" + }, + "401": { + "description": "The signature is stale or wrong, or the key that made it is not an approved device. Without one, the request reads as a guest.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + {}, + { + "devnullSignature": [] + } + ] + } + }, + "/organizations/{handle}/follow": { + "post": { + "operationId": "api-organization-follow.store", + "tags": [ + "Organizations" + ], + "parameters": [ + { + "name": "handle", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "204": { + "description": "No content" + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "403": { + "$ref": "#/components/responses/AuthorizationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + }, + "delete": { + "operationId": "api-organization-follow.destroy", + "tags": [ + "Organizations" + ], + "parameters": [ + { + "name": "handle", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "204": { + "description": "No content" + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "403": { + "$ref": "#/components/responses/AuthorizationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/organizations/{handle}/claim": { + "post": { + "operationId": "api-organization-admin.store", + "summary": "Claims the organization's page, as Claim does on the web. Someone else claiming it in between leaves it theirs", + "tags": [ + "Organizations" + ], + "parameters": [ + { + "name": "handle", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "204": { + "description": "No content" + }, + "409": { + "description": "", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "message": { + "type": "string", + "const": "Unable to claim this organization. Please try again." + } + }, + "required": [ + "message" + ] + } + } + } + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "403": { + "$ref": "#/components/responses/AuthorizationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/remotes/@{handle}/archive": { + "post": { + "operationId": "api-conversation-archive.store", + "summary": "Stashes the conversation for the user only, as the web does. It pops back into Open when either of them writes", + "tags": [ + "Remotes" + ], + "parameters": [ + { + "name": "handle", + "in": "path", + "required": true, + "description": "The partner's handle", + "schema": { + "type": "string" + } + } + ], + "responses": { + "204": { + "description": "No content" + }, + "404": { + "$ref": "#/components/responses/ModelNotFoundException" + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "403": { + "$ref": "#/components/responses/AuthorizationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + }, + "delete": { + "operationId": "api-conversation-archive.destroy", + "summary": "Pops the conversation back into Open", + "tags": [ + "Remotes" + ], + "parameters": [ + { + "name": "handle", + "in": "path", + "required": true, + "description": "The partner's handle", + "schema": { + "type": "string" + } + } + ], + "responses": { + "204": { + "description": "No content" + }, + "404": { + "$ref": "#/components/responses/ModelNotFoundException" + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "403": { + "$ref": "#/components/responses/AuthorizationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/remotes/orgs/{org}/archive": { + "post": { + "operationId": "api-org-archive.store", + "summary": "Stashes the org for the user only. It pops back into Open when anyone in it writes", + "tags": [ + "Remotes" + ], + "parameters": [ + { + "name": "org", + "in": "path", + "required": true, + "description": "The org ID", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "204": { + "description": "No content" + }, + "404": { + "$ref": "#/components/responses/ModelNotFoundException" + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "403": { + "$ref": "#/components/responses/AuthorizationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + }, + "delete": { + "operationId": "api-org-archive.destroy", + "summary": "Pops the org back into Open", + "tags": [ + "Remotes" + ], + "parameters": [ + { + "name": "org", + "in": "path", + "required": true, + "description": "The org ID", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "204": { + "description": "No content" + }, + "404": { + "$ref": "#/components/responses/ModelNotFoundException" + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "403": { + "$ref": "#/components/responses/AuthorizationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/remotes/@{handle}/mute": { + "put": { + "operationId": "api-conversation-mute.update", + "summary": "Mutes the conversation for the user only, until the chosen duration ends or forever, or unmutes it", + "tags": [ + "Remotes" + ], + "parameters": [ + { + "name": "handle", + "in": "path", + "required": true, + "description": "The partner's handle", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateApiConversationMuteRequest" + } + } + } + }, + "responses": { + "200": { + "description": "", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "muted_until_at": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "muted_until_at" + ] + } + } + } + }, + "404": { + "$ref": "#/components/responses/ModelNotFoundException" + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "403": { + "$ref": "#/components/responses/AuthorizationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/remotes/@{handle}/pin": { + "put": { + "operationId": "api-conversation-pin.update", + "tags": [ + "Remotes" + ], + "parameters": [ + { + "name": "handle", + "in": "path", + "required": true, + "description": "The partner's handle", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateApiConversationPinRequest" + } + } + } + }, + "responses": { + "200": { + "description": "", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "pinned_at": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "pinned_at" + ] + } + } + } + }, + "404": { + "$ref": "#/components/responses/ModelNotFoundException" + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "403": { + "$ref": "#/components/responses/AuthorizationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/remotes/orgs/{org}/mute": { + "put": { + "operationId": "api-org-mute.update", + "summary": "Mutes the org for the user only, until the chosen duration ends or forever, or unmutes it", + "tags": [ + "Remotes" + ], + "parameters": [ + { + "name": "org", + "in": "path", + "required": true, + "description": "The org ID", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateApiOrgMuteRequest" + } + } + } + }, + "responses": { + "200": { + "description": "", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "muted_until_at": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "muted_until_at" + ] + } + } + } + }, + "404": { + "$ref": "#/components/responses/ModelNotFoundException" + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "403": { + "$ref": "#/components/responses/AuthorizationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/remotes/orgs/{org}/pin": { + "put": { + "operationId": "api-org-pin.update", + "tags": [ + "Remotes" + ], + "parameters": [ + { + "name": "org", + "in": "path", + "required": true, + "description": "The org ID", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateApiOrgPinRequest" + } + } + } + }, + "responses": { + "200": { + "description": "", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "pinned_at": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "pinned_at" + ] + } + } + } + }, + "404": { + "$ref": "#/components/responses/ModelNotFoundException" + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "403": { + "$ref": "#/components/responses/AuthorizationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/remotes/@{handle}/merge": { + "post": { + "operationId": "api-conversation-merge.store", + "summary": "Merges a fetched request into the user's open conversations, so they can reply", + "tags": [ + "Remotes" + ], + "parameters": [ + { + "name": "handle", + "in": "path", + "required": true, + "description": "The partner's handle", + "schema": { + "type": "string" + } + } + ], + "responses": { + "204": { + "description": "No content" + }, + "404": { + "$ref": "#/components/responses/ModelNotFoundException" + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "403": { + "$ref": "#/components/responses/AuthorizationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/remotes/@{handle}/drop": { + "post": { + "operationId": "api-conversation-drop.store", + "summary": "Drops a fetched request for good, without telling the sender, whose request keeps waiting on their side", + "tags": [ + "Remotes" + ], + "parameters": [ + { + "name": "handle", + "in": "path", + "required": true, + "description": "The partner's handle", + "schema": { + "type": "string" + } + } + ], + "responses": { + "204": { + "description": "No content" + }, + "404": { + "$ref": "#/components/responses/ModelNotFoundException" + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "403": { + "$ref": "#/components/responses/AuthorizationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/remotes": { + "get": { + "operationId": "api-conversation.index", + "summary": "A page of the web's inbox, pinned first then newest first, for the Open, Fetched or Stashed tab, matching a name or handle, and\ncontinuing before a conversation, with the unread count the web's nav shows and how many requests are fetched", + "tags": [ + "Remotes" + ], + "parameters": [ + { + "name": "tab", + "in": "query", + "schema": { + "type": [ + "string", + "null" + ], + "enum": [ + "open", + "stashed", + null + ] + } + }, + { + "name": "q", + "in": "query", + "schema": { + "type": [ + "string", + "null" + ], + "maxLength": 100 + } + }, + { + "name": "before", + "in": "query", + "schema": { + "type": [ + "string", + "null" + ], + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "Array of `ConversationResource`", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ConversationResource" + } + }, + "has_more": { + "type": "boolean" + }, + "unread_count": { + "type": "integer" + }, + "requests_count": { + "type": "integer" + } + }, + "required": [ + "data", + "has_more", + "unread_count", + "requests_count" + ] + } + } + } + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "403": { + "$ref": "#/components/responses/AuthorizationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/remotes/@{handle}/messages": { + "get": { + "operationId": "api-conversation-message.index", + "summary": "The latest page of the conversation with the partner, the page before a message, or everything after one with\nthe reactions changed since a version, as the web's thread polls it. Someone the user hasn't talked to yet has\nan empty thread, which says whether a first message can go to them", + "tags": [ + "Remotes" + ], + "parameters": [ + { + "name": "handle", + "in": "path", + "required": true, + "description": "The partner's handle", + "schema": { + "type": "string" + } + }, + { + "name": "after", + "in": "query", + "schema": { + "type": [ + "integer", + "null" + ], + "minimum": 0 + } + }, + { + "name": "before", + "in": "query", + "schema": { + "type": [ + "integer", + "null" + ], + "minimum": 1 + } + }, + { + "name": "reactions_after", + "in": "query", + "schema": { + "type": [ + "integer", + "null" + ], + "minimum": 0 + } + } + ], + "responses": { + "200": { + "description": "`ConversationThreadResource`", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/ConversationThreadResource" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "404": { + "$ref": "#/components/responses/ModelNotFoundException" + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "403": { + "$ref": "#/components/responses/AuthorizationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + }, + "post": { + "operationId": "api-conversation-message.store", + "summary": "Pushes a message to the partner, starting the conversation if it is the first, as the web's composer does. Sending\nthe same client_id again, as a retry does, answers with the message it already created, with a 200 instead of a 201", + "tags": [ + "Remotes" + ], + "parameters": [ + { + "name": "handle", + "in": "path", + "required": true, + "description": "The partner's handle", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "`MessageResource`", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "allOf": [ + { + "$ref": "#/components/schemas/MessageResource" + }, + { + "type": "object", + "required": [ + "reply_to", + "link_preview", + "images", + "voice", + "reactions" + ] + } + ] + } + }, + "required": [ + "data" + ] + } + } + } + }, + "404": { + "$ref": "#/components/responses/ModelNotFoundException" + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "403": { + "$ref": "#/components/responses/AuthorizationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/remotes/@{handle}/read": { + "put": { + "operationId": "api-conversation-read.update", + "summary": "Pulls the conversation through a message, as the web does once the thread is scrolled to it. It only ever moves\nforward, and a conversation that hasn't started has nothing to pull", + "tags": [ + "Remotes" + ], + "parameters": [ + { + "name": "handle", + "in": "path", + "required": true, + "description": "The partner's handle", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateApiConversationReadRequest" + } + } + } + }, + "responses": { + "204": { + "description": "No content" + }, + "404": { + "$ref": "#/components/responses/ModelNotFoundException" + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "403": { + "$ref": "#/components/responses/AuthorizationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/remotes/orgs/{org}/messages": { + "get": { + "operationId": "api-org-message.index", + "summary": "An org's thread as the web loads and polls it, from where the user's history starts", + "tags": [ + "Remotes" + ], + "parameters": [ + { + "name": "org", + "in": "path", + "required": true, + "description": "The org ID", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "after", + "in": "query", + "schema": { + "type": [ + "integer", + "null" + ], + "minimum": 0 + } + }, + { + "name": "before", + "in": "query", + "schema": { + "type": [ + "integer", + "null" + ], + "minimum": 1 + } + }, + { + "name": "reactions_after", + "in": "query", + "schema": { + "type": [ + "integer", + "null" + ], + "minimum": 0 + } + } + ], + "responses": { + "200": { + "description": "`OrgThreadResource`", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/OrgThreadResource" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "404": { + "$ref": "#/components/responses/ModelNotFoundException" + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "403": { + "$ref": "#/components/responses/AuthorizationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + }, + "post": { + "operationId": "api-org-message.store", + "summary": "Pushes a message to the org, as the web's composer does, once however often its client_id is sent", + "tags": [ + "Remotes" + ], + "parameters": [ + { + "name": "org", + "in": "path", + "required": true, + "description": "The org ID", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "`MessageResource`", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "allOf": [ + { + "$ref": "#/components/schemas/MessageResource" + }, + { + "type": "object", + "required": [ + "reply_to", + "link_preview", + "images", + "voice", + "reactions" + ] + } + ] + } + }, + "required": [ + "data" + ] + } + } + } + }, + "404": { + "$ref": "#/components/responses/ModelNotFoundException" + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "403": { + "$ref": "#/components/responses/AuthorizationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/remotes/orgs/{org}/read": { + "put": { + "operationId": "api-org-read.update", + "summary": "Pulls the org through a message, as the web does once the thread is scrolled to it", + "tags": [ + "Remotes" + ], + "parameters": [ + { + "name": "org", + "in": "path", + "required": true, + "description": "The org ID", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateApiOrgReadRequest" + } + } + } + }, + "responses": { + "204": { + "description": "No content" + }, + "404": { + "$ref": "#/components/responses/ModelNotFoundException" + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "403": { + "$ref": "#/components/responses/AuthorizationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/remotes/messages/{message}/link-preview": { + "get": { + "operationId": "api-message-link-preview.show", + "summary": "A message's link card, which the web asks for again while it is still pending", + "tags": [ + "Remotes" + ], + "parameters": [ + { + "name": "message", + "in": "path", + "required": true, + "description": "The message ID", + "schema": { + "type": "integer" + } + } + ], + "responses": { + "200": { + "description": "", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "link_preview": { + "type": "string" + } + }, + "required": [ + "link_preview" + ] + } + } + } + }, + "404": { + "$ref": "#/components/responses/ModelNotFoundException" + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "403": { + "$ref": "#/components/responses/AuthorizationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/remotes/@{handle}/typing": { + "put": { + "operationId": "api-conversation-typing.update", + "summary": "Says the user is typing to the partner for a few seconds, as the web's composer does every few seconds while it\nhas text. A conversation that hasn't started has nobody to tell", + "tags": [ + "Remotes" + ], + "parameters": [ + { + "name": "handle", + "in": "path", + "required": true, + "description": "The partner's handle", + "schema": { + "type": "string" + } + } + ], + "responses": { + "204": { + "description": "No content" + }, + "404": { + "$ref": "#/components/responses/ModelNotFoundException" + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "403": { + "$ref": "#/components/responses/AuthorizationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/remotes/orgs/{org}/typing": { + "put": { + "operationId": "api-org-typing.update", + "summary": "Says the user is typing in the org for a few seconds", + "tags": [ + "Remotes" + ], + "parameters": [ + { + "name": "org", + "in": "path", + "required": true, + "description": "The org ID", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "204": { + "description": "No content" + }, + "404": { + "$ref": "#/components/responses/ModelNotFoundException" + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "403": { + "$ref": "#/components/responses/AuthorizationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/remotes/@{handle}/ping": { + "post": { + "operationId": "api-conversation-ping.store", + "summary": "Pings the partner, as the web's composer does, in a conversation that has already started", + "tags": [ + "Remotes" + ], + "parameters": [ + { + "name": "handle", + "in": "path", + "required": true, + "description": "The partner's handle", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "`MessageResource`", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/MessageResource" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "404": { + "$ref": "#/components/responses/ModelNotFoundException" + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "403": { + "$ref": "#/components/responses/AuthorizationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/remotes/orgs/{org}/ping": { + "post": { + "operationId": "api-org-ping.store", + "summary": "Pings everyone in the org, as the web's composer does", + "tags": [ + "Remotes" + ], + "parameters": [ + { + "name": "org", + "in": "path", + "required": true, + "description": "The org ID", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "`MessageResource`", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "allOf": [ + { + "$ref": "#/components/schemas/MessageResource" + }, + { + "type": "object", + "required": [ + "user" + ] + } + ] + } + }, + "required": [ + "data" + ] + } + } + } + }, + "404": { + "$ref": "#/components/responses/ModelNotFoundException" + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "403": { + "$ref": "#/components/responses/AuthorizationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/remotes/call": { + "get": { + "operationId": "api-call.show", + "summary": "The call ringing for the user and the calls going on in their orgs, polled as often as the web polls them", + "tags": [ + "Remotes" + ], + "responses": { + "200": { + "description": "", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "call": { + "type": [ + "object", + "null" + ], + "properties": { + "partner": { + "$ref": "#/components/schemas/UserResource" + } + }, + "required": [ + "partner" + ], + "additionalProperties": {} + }, + "org_calls": { + "type": "array", + "items": {} + } + }, + "required": [ + "call", + "org_calls" + ] + } + } + } + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/remotes/@{handle}/call": { + "get": { + "operationId": "api-conversation-call.show", + "summary": "The user's call to the partner while it rings, with the partner's answer once they accept", + "tags": [ + "Remotes" + ], + "parameters": [ + { + "name": "handle", + "in": "path", + "required": true, + "description": "The partner's handle", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "call": { + "type": [ + "object", + "null" + ], + "properties": { + "answer": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "answer" + ] + } + }, + "required": [ + "call" + ] + } + } + } + }, + "404": { + "$ref": "#/components/responses/ModelNotFoundException" + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "403": { + "$ref": "#/components/responses/AuthorizationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + }, + "put": { + "operationId": "api-conversation-call.update", + "summary": "Answers the call the partner is ringing the user with", + "tags": [ + "Remotes" + ], + "parameters": [ + { + "name": "handle", + "in": "path", + "required": true, + "description": "The partner's handle", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateApiConversationCallRequest" + } + } + } + }, + "responses": { + "204": { + "description": "No content" + }, + "404": { + "$ref": "#/components/responses/ModelNotFoundException" + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "403": { + "$ref": "#/components/responses/AuthorizationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + }, + "delete": { + "operationId": "api-conversation-call.destroy", + "summary": "Ends the call either of them is ringing the other with", + "tags": [ + "Remotes" + ], + "parameters": [ + { + "name": "handle", + "in": "path", + "required": true, + "description": "The partner's handle", + "schema": { + "type": "string" + } + }, + { + "name": "failed", + "in": "query", + "schema": { + "type": "boolean" + } + } + ], + "responses": { + "204": { + "description": "No content" + }, + "404": { + "$ref": "#/components/responses/ModelNotFoundException" + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "403": { + "$ref": "#/components/responses/AuthorizationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + }, + "post": { + "operationId": "api-conversation-call.store", + "summary": "Rings the partner with the user's offer, as the web's Call does", + "tags": [ + "Remotes" + ], + "parameters": [ + { + "name": "handle", + "in": "path", + "required": true, + "description": "The partner's handle", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateApiConversationCallRequest" + } + } + } + }, + "responses": { + "204": { + "description": "No content" + }, + "404": { + "$ref": "#/components/responses/ModelNotFoundException" + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "403": { + "$ref": "#/components/responses/AuthorizationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/remotes/orgs/{org}/call": { + "put": { + "operationId": "api-org-call.update", + "summary": "Each member checks in every couple of seconds, handing over their signals and picking up the others'", + "tags": [ + "Remotes" + ], + "parameters": [ + { + "name": "org", + "in": "path", + "required": true, + "description": "The org ID", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateApiOrgCallRequest" + } + } + } + }, + "responses": { + "200": { + "description": "", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "call": { + "type": [ + "object", + "null" + ], + "properties": { + "members": { + "type": "array", + "items": { + "$ref": "#/components/schemas/CallMemberResource" + } + }, + "signals": { + "type": "string" + } + }, + "required": [ + "members", + "signals" + ], + "additionalProperties": {} + } + }, + "required": [ + "call" + ] + } + } + } + }, + "404": { + "$ref": "#/components/responses/ModelNotFoundException" + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "403": { + "$ref": "#/components/responses/AuthorizationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + }, + "delete": { + "operationId": "api-org-call.destroy", + "summary": "Leaves the org's call", + "tags": [ + "Remotes" + ], + "parameters": [ + { + "name": "org", + "in": "path", + "required": true, + "description": "The org ID", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "204": { + "description": "No content" + }, + "404": { + "$ref": "#/components/responses/ModelNotFoundException" + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "403": { + "$ref": "#/components/responses/AuthorizationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + }, + "post": { + "operationId": "api-org-call.store", + "summary": "Starts the org's call, or joins it while it has room, as the web's Call and Join do. The call is null when it\nfilled up in between", + "tags": [ + "Remotes" + ], + "parameters": [ + { + "name": "org", + "in": "path", + "required": true, + "description": "The org ID", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "201": { + "description": "", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "call": { + "type": [ + "object", + "null" + ], + "properties": { + "members": { + "type": "array", + "items": { + "$ref": "#/components/schemas/CallMemberResource" + } + }, + "signals": { + "type": "string" + } + }, + "required": [ + "members", + "signals" + ], + "additionalProperties": {} + } + }, + "required": [ + "call" + ] + } + } + } + }, + "404": { + "$ref": "#/components/responses/ModelNotFoundException" + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "403": { + "$ref": "#/components/responses/AuthorizationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/remotes/@{handle}/call/ice-servers": { + "get": { + "operationId": "api-conversation-call-ice-server.index", + "summary": "The relay a call to the partner goes through, as the web asks for before calling or answering", + "tags": [ + "Remotes" + ], + "parameters": [ + { + "name": "handle", + "in": "path", + "required": true, + "description": "The partner's handle", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "ice_servers": { + "type": "array", + "items": { + "type": "object" + } + }, + "is_relay_only": { + "type": "boolean" + } + }, + "required": [ + "ice_servers", + "is_relay_only" + ] + } + } + } + }, + "404": { + "$ref": "#/components/responses/ModelNotFoundException" + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "403": { + "$ref": "#/components/responses/AuthorizationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/remotes/orgs/{org}/call/ice-servers": { + "get": { + "operationId": "api-org-call-ice-server.index", + "summary": "The relay the org's call goes through, as the web asks for before starting or joining it", + "tags": [ + "Remotes" + ], + "parameters": [ + { + "name": "org", + "in": "path", + "required": true, + "description": "The org ID", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "ice_servers": { + "type": "array", + "items": { + "type": "object" + } + }, + "is_relay_only": { + "type": "boolean" + } + }, + "required": [ + "ice_servers", + "is_relay_only" + ] + } + } + } + }, + "404": { + "$ref": "#/components/responses/ModelNotFoundException" + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "403": { + "$ref": "#/components/responses/AuthorizationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/remotes/reactions": { + "get": { + "operationId": "api-message-reaction.index", + "summary": "The emoji the user reacts with, most used first, which the web ranks its reaction picker by", + "tags": [ + "Remotes" + ], + "responses": { + "200": { + "description": "", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "usage": { + "type": "array", + "items": { + "type": "object", + "properties": { + "emoji": { + "type": "string" + }, + "count": { + "type": "integer" + } + }, + "required": [ + "emoji", + "count" + ] + } + } + }, + "required": [ + "usage" + ] + } + } + } + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "403": { + "$ref": "#/components/responses/AuthorizationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/remotes/messages/{message}/reactions": { + "post": { + "operationId": "api-message-reaction.store", + "summary": "Reacts with an emoji, once however often it is sent, and answers with the message's reactions in the order they\nwere left, as the web does", + "tags": [ + "Remotes" + ], + "parameters": [ + { + "name": "message", + "in": "path", + "required": true, + "description": "The message ID", + "schema": { + "type": "integer" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateApiMessageReactionRequest" + } + } + } + }, + "responses": { + "200": { + "description": "", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "reactions": { + "type": "array", + "items": { + "$ref": "#/components/schemas/MessageReaction" + } + } + }, + "required": [ + "reactions" + ] + } + } + } + }, + "404": { + "$ref": "#/components/responses/ModelNotFoundException" + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "403": { + "$ref": "#/components/responses/AuthorizationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + }, + "delete": { + "operationId": "api-message-reaction.destroy", + "tags": [ + "Remotes" + ], + "parameters": [ + { + "name": "message", + "in": "path", + "required": true, + "description": "The message ID", + "schema": { + "type": "integer" + } + }, + { + "name": "emoji", + "in": "query", + "required": true, + "schema": { + "type": "string", + "maxLength": 32 + } + } + ], + "responses": { + "200": { + "description": "", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "reactions": { + "type": "array", + "items": { + "$ref": "#/components/schemas/MessageReaction" + } + } + }, + "required": [ + "reactions" + ] + } + } + } + }, + "404": { + "$ref": "#/components/responses/ModelNotFoundException" + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "403": { + "$ref": "#/components/responses/AuthorizationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/remotes/messages/{message}/pin": { + "put": { + "operationId": "api-message-pin.update", + "tags": [ + "Remotes" + ], + "parameters": [ + { + "name": "message", + "in": "path", + "required": true, + "description": "The message ID", + "schema": { + "type": "integer" + } + } + ], + "responses": { + "200": { + "description": "", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "pinned": { + "type": "array", + "items": { + "allOf": [ + { + "$ref": "#/components/schemas/MessageResource" + }, + { + "type": "object", + "required": [ + "images", + "voice", + "reactions", + "user" + ] + } + ] + } + }, + "reactions_version": { + "type": "integer" + } + }, + "required": [ + "pinned", + "reactions_version" + ] + } + } + } + }, + "404": { + "$ref": "#/components/responses/ModelNotFoundException" + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "403": { + "$ref": "#/components/responses/AuthorizationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + }, + "delete": { + "operationId": "api-message-pin.destroy", + "tags": [ + "Remotes" + ], + "parameters": [ + { + "name": "message", + "in": "path", + "required": true, + "description": "The message ID", + "schema": { + "type": "integer" + } + } + ], + "responses": { + "200": { + "description": "", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "pinned": { + "type": "array", + "items": { + "allOf": [ + { + "$ref": "#/components/schemas/MessageResource" + }, + { + "type": "object", + "required": [ + "images", + "voice", + "reactions", + "user" + ] + } + ] + } + }, + "reactions_version": { + "type": "integer" + } + }, + "required": [ + "pinned", + "reactions_version" + ] + } + } + } + }, + "404": { + "$ref": "#/components/responses/ModelNotFoundException" + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "403": { + "$ref": "#/components/responses/AuthorizationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/remotes/candidates": { + "get": { + "operationId": "api-remote-candidate.index", + "summary": "The people matching a search, each with the reason the user can't message them or add them to the org, as the\nweb's New remote, New org and Share in Remotes pickers show them", + "tags": [ + "Remotes" + ], + "parameters": [ + { + "name": "q", + "in": "query", + "schema": { + "type": [ + "string", + "null" + ], + "maxLength": 100 + } + }, + { + "name": "org", + "in": "query", + "schema": { + "type": [ + "string", + "null" + ], + "format": "uuid" + } + }, + { + "name": "for", + "in": "query", + "schema": { + "type": [ + "string", + "null" + ], + "enum": [ + "remote", + "org", + "share", + null + ] + } + } + ], + "responses": { + "200": { + "description": "", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "candidates": { + "type": "array", + "items": { + "$ref": "#/components/schemas/RemoteCandidateResource" + } + } + }, + "required": [ + "candidates" + ] + } + } + } + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "403": { + "$ref": "#/components/responses/AuthorizationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/remotes/orgs": { + "post": { + "operationId": "api-org.store", + "summary": "Starts an org as the web's New org does: the user maintains it, and everyone they add contributes", + "tags": [ + "Remotes" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateApiOrgRequest" + } + } + } + }, + "responses": { + "201": { + "description": "", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "org": { + "type": "object", + "properties": { + "id": { + "type": "string" + } + }, + "required": [ + "id" + ] + } + }, + "required": [ + "org" + ] + } + } + } + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "403": { + "$ref": "#/components/responses/AuthorizationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/remotes/orgs/{org}": { + "put": { + "operationId": "api-org.update", + "summary": "Renames the org, or takes its name away, as the web's org settings do", + "tags": [ + "Remotes" + ], + "parameters": [ + { + "name": "org", + "in": "path", + "required": true, + "description": "The org ID", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateApiOrgRequest" + } + } + } + }, + "responses": { + "204": { + "description": "No content" + }, + "404": { + "$ref": "#/components/responses/ModelNotFoundException" + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "403": { + "$ref": "#/components/responses/AuthorizationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/remotes/orgs/{org}/members": { + "post": { + "operationId": "api-org-member.store", + "tags": [ + "Remotes" + ], + "parameters": [ + { + "name": "org", + "in": "path", + "required": true, + "description": "The org ID", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateApiOrgMemberRequest" + } + } + } + }, + "responses": { + "204": { + "description": "No content" + }, + "404": { + "$ref": "#/components/responses/ModelNotFoundException" + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "403": { + "$ref": "#/components/responses/AuthorizationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/remotes/orgs/{org}/members/{handle}": { + "put": { + "operationId": "api-org-member.update", + "tags": [ + "Remotes" + ], + "parameters": [ + { + "name": "org", + "in": "path", + "required": true, + "description": "The org ID", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "handle", + "in": "path", + "required": true, + "description": "The member's handle", + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateApiOrgMemberRequest" + } + } + } + }, + "responses": { + "204": { + "description": "No content" + }, + "404": { + "$ref": "#/components/responses/ModelNotFoundException" + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "403": { + "$ref": "#/components/responses/AuthorizationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + }, + "delete": { + "operationId": "api-org-member.destroy", + "tags": [ + "Remotes" + ], + "parameters": [ + { + "name": "org", + "in": "path", + "required": true, + "description": "The org ID", + "schema": { + "type": "string", + "format": "uuid" + } + }, + { + "name": "handle", + "in": "path", + "required": true, + "description": "The member's handle", + "schema": { + "type": "string" + } + } + ], + "responses": { + "204": { + "description": "No content" + }, + "404": { + "$ref": "#/components/responses/ModelNotFoundException" + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "403": { + "$ref": "#/components/responses/AuthorizationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/scheduled-commits": { + "get": { + "operationId": "api-scheduled-commit.index", + "summary": "The user's queue, as the web's Scheduled page lists it, 20 a page", + "tags": [ + "Scheduled commits" + ], + "responses": { + "200": { + "description": "Paginated set of `ScheduledCommitResource`", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/ScheduledCommitResource" + } + }, + "links": { + "type": "object", + "properties": { + "first": { + "type": [ + "string", + "null" + ] + }, + "last": { + "type": [ + "string", + "null" + ] + }, + "prev": { + "type": [ + "string", + "null" + ] + }, + "next": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "first", + "last", + "prev", + "next" + ] + }, + "meta": { + "type": "object", + "properties": { + "current_page": { + "type": "integer", + "minimum": 1 + }, + "from": { + "type": [ + "integer", + "null" + ], + "minimum": 1 + }, + "last_page": { + "type": "integer", + "minimum": 1 + }, + "links": { + "type": "array", + "description": "Generated paginator links.", + "items": { + "type": "object", + "properties": { + "url": { + "type": [ + "string", + "null" + ] + }, + "label": { + "type": "string" + }, + "active": { + "type": "boolean" + } + }, + "required": [ + "url", + "label", + "active" + ] + } + }, + "path": { + "type": [ + "string", + "null" + ], + "description": "Base path for paginator generated URLs." + }, + "per_page": { + "type": "integer", + "description": "Number of items shown per page.", + "minimum": 0 + }, + "to": { + "type": [ + "integer", + "null" + ], + "description": "Number of the last item in the slice.", + "minimum": 1 + }, + "total": { + "type": "integer", + "description": "Total number of items being paginated.", + "minimum": 0 + } + }, + "required": [ + "current_page", + "from", + "last_page", + "links", + "path", + "per_page", + "to", + "total" + ] + } + }, + "required": [ + "data", + "links", + "meta" + ] + } + } + } + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + }, + "post": { + "operationId": "api-scheduled-commit.store", + "summary": "Only the user sees a scheduled commit until it is submitted", + "tags": [ + "Scheduled commits" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateApiScheduledCommitRequest" + } + }, + "multipart/form-data": { + "schema": { + "type": "object", + "properties": { + "payload": { + "type": "string", + "format": "binary", + "contentMediaType": "application/json", + "description": "The request's fields, as the JSON body would send them, in a file part." + }, + "images": { + "type": "array", + "items": { + "type": "string", + "format": "binary", + "contentMediaType": "application/octet-stream", + "description": "Maximum file size: 10000 kilobytes." + } + } + }, + "required": [ + "payload", + "images" + ] + } + } + } + }, + "responses": { + "201": { + "description": "`ScheduledCommitResource`", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/ScheduledCommitResource" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/scheduled-commits/{scheduledCommit}": { + "delete": { + "operationId": "api-scheduled-commit.destroy", + "summary": "One that was already submitted or canceled can't be canceled, so the app is told to refresh, as the web says", + "tags": [ + "Scheduled commits" + ], + "parameters": [ + { + "name": "scheduledCommit", + "in": "path", + "required": true, + "description": "The scheduled commit ID", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "204": { + "description": "No content" + }, + "409": { + "description": "", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "message": { + "type": "string", + "const": "This commit was already submitted or canceled. Refresh to see its status." + } + }, + "required": [ + "message" + ] + } + } + } + }, + "404": { + "$ref": "#/components/responses/ModelNotFoundException" + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "403": { + "$ref": "#/components/responses/AuthorizationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/scheduled-commits/{scheduledCommit}/submission": { + "post": { + "operationId": "api-scheduled-commit-submission.store", + "summary": "Commits it now, before its time, and answers with it as the queue now shows it. It goes through the usual review", + "tags": [ + "Scheduled commits" + ], + "parameters": [ + { + "name": "scheduledCommit", + "in": "path", + "required": true, + "description": "The scheduled commit ID", + "schema": { + "type": "string", + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "`ScheduledCommitResource`", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/ScheduledCommitResource" + } + }, + "required": [ + "data" + ] + } + } + } + }, + "409": { + "description": "", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "message": { + "type": "string", + "const": "This commit was already submitted or canceled. Refresh to see its status." + } + }, + "required": [ + "message" + ] + } + } + } + }, + "404": { + "$ref": "#/components/responses/ModelNotFoundException" + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "403": { + "$ref": "#/components/responses/AuthorizationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/search/profiles": { + "get": { + "operationId": "api-profile-search.index", + "summary": "The people and the organizations matching a name or handle, as the web's search finds them. People come with\nwhether the user follows each one and whether each one follows them, and people the user muted or blocked, or\nwho blocked them, are left out. Organizations are only those that already have a page, with whether the user\nfollows each one", + "tags": [ + "Search" + ], + "parameters": [ + { + "name": "q", + "in": "query", + "schema": { + "type": [ + "string", + "null" + ], + "maxLength": 100 + } + } + ], + "responses": { + "200": { + "description": "", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "users": { + "type": "array", + "items": { + "$ref": "#/components/schemas/UserResource" + } + }, + "organizations": { + "type": "array", + "items": { + "$ref": "#/components/schemas/OrganizationResource" + } + } + }, + "required": [ + "users", + "organizations" + ] + } + } + } + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/search/users": { + "get": { + "operationId": "api-user-search.index", + "description": "Deprecated for the profile search, which finds organizations too: it stays for the apps that still call it.", + "summary": "The people matching a name or handle, as the web's search finds them, with whether the user follows each one and\nwhether each one follows them. People the user muted or blocked, or who blocked them, are left out", + "tags": [ + "Search" + ], + "parameters": [ + { + "name": "q", + "in": "query", + "schema": { + "type": [ + "string", + "null" + ], + "maxLength": 100 + } + } + ], + "responses": { + "200": { + "description": "Array of `UserResource`", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/UserResource" + } + } + }, + "required": [ + "data" + ] + } + } + } + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/search/commits": { + "get": { + "operationId": "api-commit-search.index", + "summary": "The commits nearest in meaning to the term, closest first, as the web's search finds them, which may be fewer than\nasked for once the irrelevant ones are left out", + "tags": [ + "Search" + ], + "parameters": [ + { + "name": "q", + "in": "query", + "required": true, + "schema": { + "type": "string", + "minLength": 3, + "maxLength": 100 + } + }, + { + "name": "limit", + "in": "query", + "schema": { + "type": [ + "integer", + "null" + ], + "minimum": 1, + "maximum": 100 + } + } + ], + "responses": { + "200": { + "description": "Array of `CommitResource`", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/CommitResource" + } + } + }, + "required": [ + "data" + ] + } + } + } + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/search/mentions": { + "get": { + "operationId": "api-mention-suggestion.index", + "summary": "The people the composer suggests for an @mention, as the web's composer suggests them, and the organizations\noutside orgs, since mentions only link to them in commits", + "tags": [ + "Search" + ], + "parameters": [ + { + "name": "q", + "in": "query", + "schema": { + "type": [ + "string", + "null" + ], + "maxLength": 100 + } + }, + { + "name": "org", + "in": "query", + "schema": { + "type": [ + "string", + "null" + ], + "format": "uuid" + } + }, + { + "name": "reply", + "in": "query", + "schema": { + "type": [ + "string", + "null" + ], + "format": "uuid" + } + }, + { + "name": "quote", + "in": "query", + "schema": { + "type": [ + "string", + "null" + ], + "format": "uuid" + } + } + ], + "responses": { + "200": { + "description": "Array of `UserResource`", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/UserResource" + } + }, + "organizations": { + "anyOf": [ + { + "type": "array", + "items": { + "type": "string" + }, + "minItems": 0, + "maxItems": 0 + }, + { + "type": "array", + "items": { + "$ref": "#/components/schemas/OrganizationResource" + } + } + ] + } + }, + "required": [ + "data", + "organizations" + ] + } + } + } + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "403": { + "$ref": "#/components/responses/AuthorizationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/search/issues": { + "get": { + "operationId": "api-issue-suggestion.index", + "summary": "The /dev/null issue with that number, as the web's composer suggests it, or null", + "tags": [ + "Search" + ], + "parameters": [ + { + "name": "q", + "in": "query", + "required": true, + "schema": { + "type": "string", + "pattern": "^[1-9][0-9]{0,9}$" + } + } + ], + "responses": { + "200": { + "description": "", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "issue": { + "type": [ + "object", + "null" + ], + "properties": { + "number": { + "type": "integer" + }, + "title": { + "type": "string" + }, + "url": { + "type": "string" + } + }, + "required": [ + "number", + "title", + "url" + ] + } + }, + "required": [ + "issue" + ] + } + } + } + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/users/{handle}": { + "get": { + "operationId": "api-user.show", + "summary": "A signed request gets the profile as the web shows it to that user, with whether they mute it, its achievements\nand Unix rank, and how many past\u00e9is it was given, which the app only shows in past\u00e9is mode, as the web does. The\npinned commit is left out of the commits list, so it comes with the profile, as on the web. Anyone gets which\nhandles the bio mentions have a page on /dev/null, by lowercase handle, so only those link to one", + "tags": [ + "Users" + ], + "parameters": [ + { + "name": "handle", + "in": "path", + "required": true, + "description": "The user's handle", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "`UserResource`\n\n`UserResource`", + "content": { + "application/json": { + "schema": { + "anyOf": [ + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/UserResource" + }, + "bio_profiles": { + "type": "string" + } + }, + "required": [ + "data", + "bio_profiles" + ] + }, + { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/UserResource" + }, + "is_following": { + "type": "boolean" + }, + "follows_you": { + "type": "boolean" + }, + "is_muting": { + "type": "boolean" + }, + "pasteis_received": { + "type": "integer" + }, + "activity": { + "type": "object", + "properties": { + "scale": { + "type": "null" + }, + "buckets": { + "type": "array", + "items": {} + } + }, + "required": [ + "scale", + "buckets" + ] + }, + "streaks": { + "type": "object", + "properties": { + "longest": {}, + "current": { + "type": "integer", + "enum": [ + 1, + 0 + ] + } + }, + "required": [ + "longest", + "current" + ] + }, + "achievements": { + "type": "object" + }, + "pinned_commit": { + "anyOf": [ + { + "$ref": "#/components/schemas/CommitResource" + }, + { + "type": "null" + } + ] + }, + "bio_profiles": { + "type": "string" + } + }, + "required": [ + "data", + "is_following", + "follows_you", + "is_muting", + "pasteis_received", + "activity", + "streaks", + "achievements", + "pinned_commit", + "bio_profiles" + ] + } + ] + } + } + } + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "401": { + "description": "The signature is stale or wrong, or the key that made it is not an approved device. Without one, the request reads as a guest.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + {}, + { + "devnullSignature": [] + } + ] + } + }, + "/users/{handle}/commits": { + "get": { + "operationId": "api-user-commit.index", + "summary": "A signed request gets the profile's Commits or Replies tab as the web shows it to that user", + "tags": [ + "Users" + ], + "parameters": [ + { + "name": "handle", + "in": "path", + "required": true, + "description": "The user's handle", + "schema": { + "type": "string" + } + }, + { + "name": "replies", + "in": "query", + "schema": { + "type": [ + "boolean", + "null" + ] + } + } + ], + "responses": { + "200": { + "description": "Paginated set of `CommitResource`", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/CommitResource" + } + }, + "links": { + "type": "object", + "properties": { + "first": { + "type": [ + "string", + "null" + ] + }, + "last": { + "type": [ + "string", + "null" + ] + }, + "prev": { + "type": [ + "string", + "null" + ] + }, + "next": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "first", + "last", + "prev", + "next" + ] + }, + "meta": { + "type": "object", + "properties": { + "path": { + "type": [ + "string", + "null" + ], + "description": "Base path for paginator generated URLs." + }, + "per_page": { + "type": "integer", + "description": "Number of items shown per page.", + "minimum": 0 + }, + "next_cursor": { + "type": [ + "string", + "null" + ], + "description": "The \"cursor\" that points to the next set of items." + }, + "prev_cursor": { + "type": [ + "string", + "null" + ], + "description": "The \"cursor\" that points to the previous set of items." + } + }, + "required": [ + "path", + "per_page", + "next_cursor", + "prev_cursor" + ] + } + }, + "required": [ + "data", + "links", + "meta" + ] + } + } + } + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "401": { + "description": "The signature is stale or wrong, or the key that made it is not an approved device. Without one, the request reads as a guest.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + {}, + { + "devnullSignature": [] + } + ] + } + }, + "/users/{handle}/followers": { + "get": { + "operationId": "api-user-followers.index", + "summary": "The people following a user, 30 a page as on the web, with whether the signed-in user follows each one, and whether\neach one follows them", + "tags": [ + "Users" + ], + "parameters": [ + { + "name": "handle", + "in": "path", + "required": true, + "description": "The user's handle", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Paginated set of `UserResource`", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/UserResource" + } + }, + "links": { + "type": "object", + "properties": { + "first": { + "type": [ + "string", + "null" + ] + }, + "last": { + "type": [ + "string", + "null" + ] + }, + "prev": { + "type": [ + "string", + "null" + ] + }, + "next": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "first", + "last", + "prev", + "next" + ] + }, + "meta": { + "type": "object", + "properties": { + "path": { + "type": [ + "string", + "null" + ], + "description": "Base path for paginator generated URLs." + }, + "per_page": { + "type": "integer", + "description": "Number of items shown per page.", + "minimum": 0 + }, + "next_cursor": { + "type": [ + "string", + "null" + ], + "description": "The \"cursor\" that points to the next set of items." + }, + "prev_cursor": { + "type": [ + "string", + "null" + ], + "description": "The \"cursor\" that points to the previous set of items." + } + }, + "required": [ + "path", + "per_page", + "next_cursor", + "prev_cursor" + ] + } + }, + "required": [ + "data", + "links", + "meta" + ] + } + } + } + }, + "404": { + "$ref": "#/components/responses/ModelNotFoundException" + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/users/{handle}/following": { + "get": { + "operationId": "api-user-following.index", + "summary": "The people a user follows, 30 a page as on the web, with whether the signed-in user follows each one, and whether\neach one follows them", + "tags": [ + "Users" + ], + "parameters": [ + { + "name": "handle", + "in": "path", + "required": true, + "description": "The user's handle", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Paginated set of `UserResource`", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/UserResource" + } + }, + "links": { + "type": "object", + "properties": { + "first": { + "type": [ + "string", + "null" + ] + }, + "last": { + "type": [ + "string", + "null" + ] + }, + "prev": { + "type": [ + "string", + "null" + ] + }, + "next": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "first", + "last", + "prev", + "next" + ] + }, + "meta": { + "type": "object", + "properties": { + "path": { + "type": [ + "string", + "null" + ], + "description": "Base path for paginator generated URLs." + }, + "per_page": { + "type": "integer", + "description": "Number of items shown per page.", + "minimum": 0 + }, + "next_cursor": { + "type": [ + "string", + "null" + ], + "description": "The \"cursor\" that points to the next set of items." + }, + "prev_cursor": { + "type": [ + "string", + "null" + ], + "description": "The \"cursor\" that points to the previous set of items." + } + }, + "required": [ + "path", + "per_page", + "next_cursor", + "prev_cursor" + ] + } + }, + "required": [ + "data", + "links", + "meta" + ] + } + } + } + }, + "404": { + "$ref": "#/components/responses/ModelNotFoundException" + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/users/{handle}/following/organizations": { + "get": { + "operationId": "api-user-followed-organization.index", + "summary": "The organizations a user follows, 30 a page, newest follow first, with whether the signed-in user follows each one", + "tags": [ + "Users" + ], + "parameters": [ + { + "name": "handle", + "in": "path", + "required": true, + "description": "The user's handle", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Paginated set of `OrganizationResource`", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/OrganizationResource" + } + }, + "links": { + "type": "object", + "properties": { + "first": { + "type": [ + "string", + "null" + ] + }, + "last": { + "type": [ + "string", + "null" + ] + }, + "prev": { + "type": [ + "string", + "null" + ] + }, + "next": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "first", + "last", + "prev", + "next" + ] + }, + "meta": { + "type": "object", + "properties": { + "path": { + "type": [ + "string", + "null" + ], + "description": "Base path for paginator generated URLs." + }, + "per_page": { + "type": "integer", + "description": "Number of items shown per page.", + "minimum": 0 + }, + "next_cursor": { + "type": [ + "string", + "null" + ], + "description": "The \"cursor\" that points to the next set of items." + }, + "prev_cursor": { + "type": [ + "string", + "null" + ], + "description": "The \"cursor\" that points to the previous set of items." + } + }, + "required": [ + "path", + "per_page", + "next_cursor", + "prev_cursor" + ] + } + }, + "required": [ + "data", + "links", + "meta" + ] + } + } + } + }, + "404": { + "$ref": "#/components/responses/ModelNotFoundException" + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/users/{handle}/follow": { + "post": { + "operationId": "api-user-follow.store", + "tags": [ + "Users" + ], + "parameters": [ + { + "name": "handle", + "in": "path", + "required": true, + "description": "The user's handle", + "schema": { + "type": "string" + } + } + ], + "responses": { + "204": { + "description": "No content" + }, + "404": { + "$ref": "#/components/responses/ModelNotFoundException" + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "403": { + "$ref": "#/components/responses/AuthorizationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + }, + "delete": { + "operationId": "api-user-follow.destroy", + "tags": [ + "Users" + ], + "parameters": [ + { + "name": "handle", + "in": "path", + "required": true, + "description": "The user's handle", + "schema": { + "type": "string" + } + } + ], + "responses": { + "204": { + "description": "No content" + }, + "404": { + "$ref": "#/components/responses/ModelNotFoundException" + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/users/{handle}/dismiss": { + "post": { + "operationId": "api-suggestion-dismissal.store", + "summary": "Not interested, as on the web: they are never suggested again, and nothing else changes", + "tags": [ + "Users" + ], + "parameters": [ + { + "name": "handle", + "in": "path", + "required": true, + "description": "The user's handle", + "schema": { + "type": "string" + } + } + ], + "responses": { + "204": { + "description": "No content" + }, + "404": { + "$ref": "#/components/responses/ModelNotFoundException" + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "403": { + "$ref": "#/components/responses/AuthorizationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/users/{handle}/mute": { + "post": { + "operationId": "api-user-mute.store", + "summary": "Mutes the user silently, as on the web, and answers with them and that they are now muted", + "tags": [ + "Users" + ], + "parameters": [ + { + "name": "handle", + "in": "path", + "required": true, + "description": "The user's handle", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "`UserResource`", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/UserResource" + }, + "is_muting": { + "type": "boolean" + } + }, + "required": [ + "data", + "is_muting" + ] + } + } + } + }, + "404": { + "$ref": "#/components/responses/ModelNotFoundException" + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "403": { + "$ref": "#/components/responses/AuthorizationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + }, + "delete": { + "operationId": "api-user-mute.destroy", + "tags": [ + "Users" + ], + "parameters": [ + { + "name": "handle", + "in": "path", + "required": true, + "description": "The user's handle", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "`UserResource`", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/UserResource" + }, + "is_muting": { + "type": "boolean" + } + }, + "required": [ + "data", + "is_muting" + ] + } + } + } + }, + "404": { + "$ref": "#/components/responses/ModelNotFoundException" + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + }, + "/users/{handle}/block": { + "post": { + "operationId": "api-user-block.store", + "summary": "Blocks the user, which ends the follows both ways, as on the web, and answers with them and that they are now\nblocked", + "tags": [ + "Users" + ], + "parameters": [ + { + "name": "handle", + "in": "path", + "required": true, + "description": "The user's handle", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "`UserResource`", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/UserResource" + }, + "is_blocking": { + "type": "boolean" + } + }, + "required": [ + "data", + "is_blocking" + ] + } + } + } + }, + "404": { + "$ref": "#/components/responses/ModelNotFoundException" + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "403": { + "$ref": "#/components/responses/AuthorizationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + }, + "delete": { + "operationId": "api-user-block.destroy", + "summary": "Unblocking doesn't bring back the follows, as on the web", + "tags": [ + "Users" + ], + "parameters": [ + { + "name": "handle", + "in": "path", + "required": true, + "description": "The user's handle", + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "`UserResource`", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "data": { + "$ref": "#/components/schemas/UserResource" + }, + "is_blocking": { + "type": "boolean" + } + }, + "required": [ + "data", + "is_blocking" + ] + } + } + } + }, + "404": { + "$ref": "#/components/responses/ModelNotFoundException" + }, + "422": { + "$ref": "#/components/responses/ValidationException" + }, + "401": { + "description": "The signature is missing, stale or wrong, or the key that made it is not an approved device.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ApiError" + } + } + } + }, + "429": { + "description": "Too many requests. Wait for the `Retry-After` seconds before trying again.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RateLimitError" + } + } + } + } + }, + "security": [ + { + "devnullSignature": [] + } + ] + } + } + }, + "components": { + "securitySchemes": { + "devnullSignature": { + "type": "apiKey", + "description": "An SSH signature, in the `devnull-api` namespace, of the request's `X-Devnull-Timestamp`, `X-Devnull-Nonce`, method, path and query, and body, one per line, made with a key the user approved as a device.", + "in": "header", + "name": "X-SSH-Signature" + } + }, + "schemas": { + "ApiError": { + "type": "object", + "properties": { + "message": { + "type": "string", + "description": "What went wrong, as the web says it." + }, + "code": { + "type": "string", + "description": "Which error it is. A code never changes once released.", + "enum": [ + "invalid_signature", + "device_not_approved", + "invalid_grant", + "user_blocked", + "user_unavailable", + "own_commit", + "commit_unavailable", + "pasteis_exhausted", + "rate_limited", + "github_sync_failed", + "timed_out", + "banned", + "commit_rules_required", + "github_issue_refused", + "github_issue_unanswered" + ] + } + }, + "required": [ + "message", + "code" + ], + "title": "ApiError" + }, + "CallMemberResource": { + "type": "object", + "properties": { + "user": { + "$ref": "#/components/schemas/UserResource" + }, + "joined_at": { + "type": "string" + } + }, + "required": [ + "user", + "joined_at" + ], + "title": "CallMemberResource" + }, + "CommitImage": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "width": { + "type": "integer" + }, + "height": { + "type": "integer" + }, + "description": { + "type": [ + "string", + "null" + ] + }, + "url": { + "type": "string" + } + }, + "required": [ + "id", + "width", + "height", + "description", + "url" + ], + "title": "CommitImage" + }, + "CommitResource": { + "anyOf": [ + { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "short_hash": { + "type": "string" + }, + "body": { + "type": "string" + }, + "parent_id": { + "type": [ + "string", + "null" + ] + }, + "html_url": { + "type": "string" + }, + "created_at": { + "type": "string" + }, + "stars_count": { + "type": [ + "integer", + "object" + ] + }, + "replies_count": { + "type": [ + "integer", + "object" + ] + }, + "link_preview": { + "anyOf": [ + { + "$ref": "#/components/schemas/LinkPreview" + }, + { + "type": "null" + }, + { + "type": "object" + } + ] + }, + "images": { + "anyOf": [ + { + "type": "array", + "items": { + "anyOf": [ + { + "$ref": "#/components/schemas/CommitImage" + }, + { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "width": { + "type": "integer" + }, + "height": { + "type": "integer" + }, + "description": { + "type": [ + "string", + "null" + ] + }, + "url": { + "type": "string" + } + }, + "required": [ + "id", + "width", + "height", + "description", + "url" + ] + } + ] + } + }, + { + "type": "object" + } + ] + }, + "author": { + "$ref": "#/components/schemas/ProfileResource" + }, + "body_segments": { + "anyOf": [ + { + "type": "array", + "prefixItems": [ + { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "text" + }, + "text": { + "type": "string" + } + }, + "required": [ + "type", + "text" + ] + } + ], + "minItems": 1, + "maxItems": 1 + }, + { + "type": "array", + "items": { + "anyOf": [ + { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "block" + }, + "language": { + "type": [ + "string", + "null" + ] + }, + "filename": { + "type": [ + "string", + "null" + ] + }, + "html": { + "type": "string" + } + }, + "required": [ + "type", + "language", + "filename", + "html" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "code" + }, + "code": { + "type": "string" + } + }, + "required": [ + "type", + "code" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "text" + }, + "text": { + "type": "string" + } + }, + "required": [ + "type", + "text" + ] + } + ] + } + } + ] + }, + "preview_segments": { + "anyOf": [ + { + "type": "null" + }, + { + "type": "array", + "prefixItems": [ + { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "text" + }, + "text": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "type", + "text" + ] + } + ], + "minItems": 1, + "maxItems": 1 + }, + { + "type": "array", + "items": { + "anyOf": [ + { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "block" + }, + "language": { + "type": [ + "string", + "null" + ] + }, + "filename": { + "type": [ + "string", + "null" + ] + }, + "html": { + "type": "string" + } + }, + "required": [ + "type", + "language", + "filename", + "html" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "code" + }, + "code": { + "type": "string" + } + }, + "required": [ + "type", + "code" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "text" + }, + "text": { + "type": "string" + } + }, + "required": [ + "type", + "text" + ] + } + ] + } + } + ] + }, + "mentions": { + "type": "array", + "items": { + "type": "object", + "properties": { + "handle": { + "type": "string" + }, + "offset": { + "type": "integer" + }, + "length": { + "type": "integer" + }, + "kind": { + "type": "string", + "enum": [ + "organization", + "user" + ] + } + }, + "required": [ + "handle", + "offset", + "length", + "kind" + ] + } + }, + "status": { + "$ref": "#/components/schemas/CommitStatus" + }, + "is_pinned": { + "type": "boolean" + }, + "starred": { + "type": [ + "boolean", + "object" + ] + }, + "pasteis_count": { + "type": "integer" + }, + "deleted_at": { + "type": "null" + }, + "parent": { + "anyOf": [ + { + "$ref": "#/components/schemas/CommitResource" + }, + { + "type": "object" + } + ] + }, + "quoted_commit_id": { + "type": [ + "string", + "null" + ] + }, + "quoted_commit": { + "anyOf": [ + { + "$ref": "#/components/schemas/CommitResource" + }, + { + "type": "object" + } + ] + }, + "poll": { + "anyOf": [ + { + "$ref": "#/components/schemas/PollResource" + }, + { + "type": "object" + } + ] + }, + "reply_preview": { + "anyOf": [ + { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "$ref": "#/components/schemas/CommitResource" + } + }, + "next_cursor": {} + }, + "required": [ + "data", + "next_cursor" + ] + }, + { + "type": "object" + } + ] + } + }, + "required": [ + "id", + "short_hash", + "body", + "parent_id", + "html_url", + "created_at", + "stars_count", + "replies_count", + "link_preview", + "images", + "author", + "body_segments", + "preview_segments", + "mentions", + "status", + "is_pinned", + "starred", + "pasteis_count", + "deleted_at", + "parent", + "quoted_commit_id", + "quoted_commit", + "poll", + "reply_preview" + ] + }, + { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "short_hash": { + "type": "string" + }, + "body": { + "type": "string" + }, + "parent_id": { + "type": [ + "string", + "null" + ] + }, + "html_url": { + "type": "string" + }, + "created_at": { + "type": "string" + }, + "stars_count": { + "type": [ + "integer", + "object" + ] + }, + "replies_count": { + "type": [ + "integer", + "object" + ] + }, + "link_preview": { + "anyOf": [ + { + "$ref": "#/components/schemas/LinkPreview" + }, + { + "type": "null" + }, + { + "type": "object" + } + ] + }, + "images": { + "anyOf": [ + { + "type": "array", + "items": { + "anyOf": [ + { + "$ref": "#/components/schemas/CommitImage" + }, + { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "width": { + "type": "integer" + }, + "height": { + "type": "integer" + }, + "description": { + "type": [ + "string", + "null" + ] + }, + "url": { + "type": "string" + } + }, + "required": [ + "id", + "width", + "height", + "description", + "url" + ] + } + ] + } + }, + { + "type": "object" + } + ] + }, + "author": { + "$ref": "#/components/schemas/ProfileResource" + } + }, + "required": [ + "id", + "short_hash", + "body", + "parent_id", + "html_url", + "created_at", + "stars_count", + "replies_count", + "link_preview", + "images", + "author" + ] + }, + { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "parent_id": { + "type": [ + "string", + "null" + ] + }, + "deleted_at": { + "type": [ + "string", + "null" + ] + }, + "replies_count": { + "type": [ + "integer", + "object" + ] + } + }, + "required": [ + "id", + "parent_id", + "deleted_at", + "replies_count" + ] + } + ], + "title": "CommitResource" + }, + "CommitStatus": { + "type": "string", + "enum": [ + "pending", + "approved", + "rejected" + ], + "title": "CommitStatus" + }, + "ConversationMuteDuration": { + "type": "string", + "description": "How long a remote stays muted for the user who muted it.\n", + "enum": [ + "hour", + "tomorrow", + "week", + "forever", + "off" + ], + "title": "ConversationMuteDuration" + }, + "ConversationResource": { + "type": "object", + "properties": { + "partner": { + "anyOf": [ + { + "$ref": "#/components/schemas/UserResource" + }, + { + "type": "null" + } + ] + }, + "members": { + "type": [ + "string", + "null" + ] + }, + "last_message": { + "anyOf": [ + { + "$ref": "#/components/schemas/MessageResource" + }, + { + "type": "null" + } + ] + } + }, + "required": [ + "partner", + "members", + "last_message" + ], + "additionalProperties": {}, + "title": "ConversationResource" + }, + "ConversationThreadResource": { + "type": "object", + "properties": { + "partner": { + "$ref": "#/components/schemas/UserResource" + }, + "messages": { + "type": "array", + "items": { + "$ref": "#/components/schemas/MessageResource" + } + } + }, + "required": [ + "partner", + "messages" + ], + "additionalProperties": {}, + "title": "ConversationThreadResource" + }, + "CreateApiCommitPollVoteRequest": { + "type": "object", + "properties": { + "option": { + "type": "string", + "format": "uuid" + } + }, + "required": [ + "option" + ], + "title": "CreateApiCommitPollVoteRequest" + }, + "CreateApiCommitPreviewRequest": { + "type": "object", + "properties": { + "body": { + "type": "string", + "description": "At most 4,000 characters, where a link outside code counts as 23 at most. Each link must be 2,048 characters at most.", + "minLength": 1, + "maxLength": 40000 + } + }, + "required": [ + "body" + ], + "title": "CreateApiCommitPreviewRequest" + }, + "CreateApiCommitReportRequest": { + "type": "object", + "description": "A report sent as JSON, or with screenshots as multipart (see SignedRequests), checked as the web checks them.", + "properties": { + "image_descriptions": { + "type": [ + "array", + "null" + ], + "items": { + "type": [ + "string", + "null" + ], + "maxLength": 1000 + } + }, + "reason": { + "type": "string", + "enum": [ + "spam", + "harassment", + "unsafe", + "other" + ] + }, + "details": { + "type": [ + "string", + "null" + ], + "maxLength": 500 + } + }, + "required": [ + "reason" + ], + "title": "CreateApiCommitReportRequest" + }, + "CreateApiCommitRequest": { + "type": "object", + "description": "A commit from the mobile app, sent as JSON, or with images as multipart (see SignedRequests). It may reply to a commit\nor quote one, as on the web, but not both. The images are checked as the web checks them. A reply may also go to\nanyone its parent was addressed to, as the web's Replying to picks them.", + "properties": { + "body": { + "type": "string", + "description": "At most 4,000 characters, where a link outside code counts as 23 at most. Each link must be 2,048 characters at most.", + "minLength": 1, + "maxLength": 40000 + }, + "author": { + "type": [ + "string", + "null" + ] + }, + "parent_id": { + "type": [ + "string", + "null" + ], + "format": "uuid" + }, + "reply_recipients": { + "type": "array", + "items": { + "type": "string" + }, + "uniqueItems": true + }, + "quoted_commit_id": { + "type": [ + "string", + "null" + ], + "format": "uuid" + }, + "poll": { + "type": [ + "object", + "null" + ], + "properties": { + "options": { + "type": "array", + "items": { + "type": "string", + "maxLength": 50 + }, + "uniqueItems": true + }, + "duration": { + "$ref": "#/components/schemas/PollDuration" + } + }, + "required": [ + "options", + "duration" + ] + }, + "image_descriptions": { + "type": [ + "array", + "null" + ], + "items": { + "type": [ + "string", + "null" + ], + "maxLength": 1000 + } + } + }, + "required": [ + "body" + ], + "title": "CreateApiCommitRequest" + }, + "CreateApiCommitTranslationRequest": { + "type": "object", + "properties": { + "language": { + "type": "string", + "enum": [ + "af", + "agq", + "ak", + "am", + "ar", + "as", + "asa", + "ast", + "az", + "ba", + "bas", + "be", + "bem", + "bez", + "bg", + "bgc", + "bho", + "blo", + "bm", + "bn", + "bo", + "br", + "brx", + "bs", + "bua", + "ca", + "ccp", + "ce", + "ceb", + "cgg", + "chr", + "ckb", + "cs", + "csw", + "cv", + "cy", + "da", + "dav", + "de", + "dje", + "doi", + "dsb", + "dua", + "dyo", + "dz", + "ebu", + "ee", + "el", + "en", + "eo", + "es", + "et", + "eu", + "ewo", + "fa", + "ff", + "fi", + "fil", + "fo", + "fr", + "fur", + "fy", + "ga", + "gaa", + "gd", + "gl", + "gsw", + "gu", + "guz", + "gv", + "ha", + "haw", + "he", + "hi", + "hr", + "hsb", + "hu", + "hy", + "ia", + "id", + "ie", + "ig", + "ii", + "is", + "it", + "ja", + "jgo", + "jmc", + "jv", + "ka", + "kab", + "kam", + "kde", + "kea", + "kgp", + "khq", + "ki", + "kk", + "kkj", + "kl", + "kln", + "km", + "kn", + "ko", + "kok", + "ks", + "ksb", + "ksf", + "ksh", + "ku", + "kw", + "kxv", + "ky", + "lag", + "lb", + "lg", + "lij", + "lkt", + "lmo", + "ln", + "lo", + "lrc", + "lt", + "lu", + "luo", + "luy", + "lv", + "mai", + "mas", + "mer", + "mfe", + "mg", + "mgh", + "mgo", + "mi", + "mk", + "ml", + "mn", + "mni", + "mr", + "ms", + "mt", + "mua", + "my", + "mzn", + "naq", + "nb", + "nd", + "nds", + "ne", + "nl", + "nmg", + "nn", + "nnh", + "no", + "nqo", + "nso", + "nus", + "nyn", + "oc", + "om", + "or", + "os", + "pa", + "pcm", + "pl", + "pms", + "prg", + "ps", + "pt", + "qu", + "raj", + "rm", + "rn", + "ro", + "rof", + "ru", + "rw", + "rwk", + "sa", + "sah", + "saq", + "sat", + "sbp", + "sc", + "scn", + "sd", + "se", + "seh", + "ses", + "sg", + "shi", + "shn", + "si", + "sk", + "sl", + "smn", + "sn", + "so", + "sq", + "sr", + "st", + "su", + "sv", + "sw", + "syr", + "szl", + "ta", + "te", + "teo", + "tg", + "th", + "ti", + "tk", + "tn", + "to", + "tok", + "tr", + "tt", + "twq", + "tyv", + "tzm", + "ug", + "uk", + "ur", + "uz", + "vai", + "vec", + "vi", + "vmw", + "vun", + "wae", + "wo", + "xh", + "xnr", + "xog", + "yav", + "yi", + "yo", + "yrl", + "yue", + "za", + "zgh", + "zh", + "zu" + ] + } + }, + "required": [ + "language" + ], + "title": "CreateApiCommitTranslationRequest" + }, + "CreateApiConversationCallRequest": { + "type": "object", + "properties": { + "sdp": { + "type": "string", + "maxLength": 10000 + } + }, + "required": [ + "sdp" + ], + "title": "CreateApiConversationCallRequest" + }, + "CreateApiIssueRequest": { + "type": "object", + "properties": { + "command": { + "type": "string", + "enum": [ + "/feature", + "/bug" + ] + }, + "body": { + "type": "string", + "minLength": 3, + "maxLength": 4000 + }, + "environment": { + "type": "object", + "properties": { + "browser": { + "type": [ + "string", + "null" + ], + "maxLength": 100 + }, + "os": { + "type": [ + "string", + "null" + ], + "maxLength": 100 + }, + "viewport": { + "type": [ + "string", + "null" + ], + "maxLength": 100 + }, + "pixel_ratio": { + "type": [ + "string", + "null" + ], + "maxLength": 100 + }, + "language": { + "type": [ + "string", + "null" + ], + "maxLength": 100 + }, + "color_scheme": { + "type": [ + "string", + "null" + ], + "maxLength": 100 + }, + "page": { + "type": [ + "string", + "null" + ], + "maxLength": 100 + } + } + } + }, + "required": [ + "command", + "body" + ], + "title": "CreateApiIssueRequest" + }, + "CreateApiMessageReactionRequest": { + "type": "object", + "properties": { + "emoji": { + "type": "string", + "enum": [ + "\ud83d\udc4d", + "\ud83d\udc4e", + "\ud83d\udcaf", + "\ud83d\udd22", + "\ud83e\udd47", + "\ud83e\udd48", + "\ud83e\udd49", + "\ud83c\udfb1", + "\ud83c\udd70\ufe0f", + "\ud83c\udd8e", + "\ud83e\uddee", + "\ud83d\udd24", + "\ud83d\udd21", + "\ud83c\ude51", + "\ud83e\ude97", + "\ud83e\ude79", + "\ud83e\uddd1", + "\ud83d\udea1", + "\ud83c\udde6\ud83c\uddeb", + "\u2708\ufe0f", + "\ud83c\udde6\ud83c\uddfd", + "\u23f0", + "\ud83c\udde6\ud83c\uddf1", + "\u2697\ufe0f", + "\ud83c\udde9\ud83c\uddff", + "\ud83d\udc7d", + "\ud83d\ude91", + "\ud83c\udde6\ud83c\uddf8", + "\ud83c\udffa", + "\ud83e\udec0", + "\u2693", + "\ud83c\udde6\ud83c\udde9", + "\ud83d\udc7c", + "\ud83d\udca2", + "\ud83c\udde6\ud83c\uddf4", + "\ud83d\ude20", + "\ud83c\udde6\ud83c\uddee", + "\ud83d\ude27", + "\ud83d\udc1c", + "\ud83c\udde6\ud83c\uddf6", + "\ud83c\udde6\ud83c\uddec", + "\ud83c\udf4e", + "\u2652", + "\ud83c\udde6\ud83c\uddf7", + "\u2648", + "\ud83c\udde6\ud83c\uddf2", + "\u25c0\ufe0f", + "\u23ec", + "\u23eb", + "\u2b07\ufe0f", + "\ud83d\udd3d", + "\u25b6\ufe0f", + "\u2935\ufe0f", + "\u2934\ufe0f", + "\u2b05\ufe0f", + "\u2199\ufe0f", + "\u2198\ufe0f", + "\u27a1\ufe0f", + "\u21aa\ufe0f", + "\u2b06\ufe0f", + "\u2195\ufe0f", + "\ud83d\udd3c", + "\u2196\ufe0f", + "\u2197\ufe0f", + "\ud83d\udd03", + "\ud83d\udd04", + "\ud83c\udfa8", + "\ud83d\ude9b", + "\ud83d\udef0\ufe0f", + "\ud83e\uddd1\u200d\ud83c\udfa8", + "\ud83c\udde6\ud83c\uddfc", + "\ud83c\udde6\ud83c\udde8", + "*\ufe0f\u20e3", + "\ud83d\ude32", + "\ud83e\uddd1\u200d\ud83d\ude80", + "\ud83d\udc5f", + "\ud83c\udfe7", + "\u269b\ufe0f", + "\ud83c\udde6\ud83c\uddfa", + "\ud83c\udde6\ud83c\uddf9", + "\ud83d\udefa", + "\ud83e\udd51", + "\ud83e\ude93", + "\ud83c\udde6\ud83c\uddff", + "\ud83c\udd71\ufe0f", + "\ud83d\udc76", + "\ud83c\udf7c", + "\ud83d\udc24", + "\ud83d\udebc", + "\ud83d\udd19", + "\ud83e\udd53", + "\ud83e\udda1", + "\ud83c\udff8", + "\ud83e\udd6f", + "\ud83d\udec4", + "\ud83e\udd56", + "\ud83c\udde7\ud83c\uddf8", + "\ud83c\udde7\ud83c\udded", + "\u2696\ufe0f", + "\ud83d\udc68\u200d\ud83e\uddb2", + "\ud83d\udc69\u200d\ud83e\uddb2", + "\ud83e\ude70", + "\ud83c\udf88", + "\ud83d\uddf3\ufe0f", + "\u2611\ufe0f", + "\ud83c\udf8d", + "\ud83c\udf4c", + "\u203c\ufe0f", + "\ud83c\udde7\ud83c\udde9", + "\ud83e\ude95", + "\ud83c\udfe6", + "\ud83d\udcca", + "\ud83c\udde7\ud83c\udde7", + "\ud83d\udc88", + "\u26be", + "\ud83e\uddfa", + "\ud83c\udfc0", + "\u26f9\ufe0f\u200d\u2642\ufe0f", + "\u26f9\ufe0f\u200d\u2640\ufe0f", + "\ud83e\udd87", + "\ud83d\udec0", + "\ud83d\udec1", + "\ud83d\udd0b", + "\ud83c\udfd6\ufe0f", + "\ud83e\uded8", + "\ud83d\udc3b", + "\ud83e\uddd4", + "\ud83e\uddab", + "\ud83d\udecf\ufe0f", + "\ud83d\udc1d", + "\ud83c\udf7a", + "\ud83c\udf7b", + "\ud83e\udeb2", + "\ud83d\udd30", + "\ud83c\udde7\ud83c\uddfe", + "\ud83c\udde7\ud83c\uddea", + "\ud83c\udde7\ud83c\uddff", + "\ud83d\udd14", + "\ud83e\uded1", + "\ud83d\udece\ufe0f", + "\ud83c\udde7\ud83c\uddef", + "\ud83c\udf71", + "\ud83c\udde7\ud83c\uddf2", + "\ud83e\uddc3", + "\ud83c\udde7\ud83c\uddf9", + "\ud83d\udeb4", + "\ud83d\udeb2", + "\ud83d\udeb4\u200d\u2642\ufe0f", + "\ud83d\udeb4\u200d\u2640\ufe0f", + "\ud83d\udc59", + "\ud83e\udde2", + "\u2623\ufe0f", + "\ud83d\udc26", + "\ud83c\udf82", + "\ud83e\uddac", + "\ud83e\udee6", + "\ud83d\udc26\u200d\u2b1b", + "\ud83d\udc08\u200d\u2b1b", + "\u26ab", + "\ud83c\udff4", + "\ud83d\udda4", + "\ud83c\udccf", + "\u2b1b", + "\u25fe", + "\u25fc\ufe0f", + "\u2712\ufe0f", + "\u25aa\ufe0f", + "\ud83d\udd32", + "\ud83d\udc71\u200d\u2642\ufe0f", + "\ud83d\udc71", + "\ud83d\udc71\u200d\u2640\ufe0f", + "\ud83c\udf3c", + "\ud83d\udc21", + "\ud83d\udcd8", + "\ud83d\ude99", + "\ud83d\udc99", + "\ud83d\udfe6", + "\ud83e\uded0", + "\ud83d\ude0a", + "\ud83d\udc17", + "\u26f5", + "\ud83c\udde7\ud83c\uddf4", + "\ud83d\udca3", + "\ud83e\uddb4", + "\ud83d\udcd6", + "\ud83d\udd16", + "\ud83d\udcd1", + "\ud83d\udcda", + "\ud83d\udca5", + "\ud83e\ude83", + "\ud83d\udc62", + "\ud83c\udde7\ud83c\udde6", + "\ud83c\udde7\ud83c\uddfc", + "\u26f9\ufe0f", + "\ud83d\udc90", + "\ud83c\udde7\ud83c\uddfb", + "\ud83d\ude47", + "\ud83c\udff9", + "\ud83d\ude47\u200d\u2642\ufe0f", + "\ud83d\ude47\u200d\u2640\ufe0f", + "\ud83e\udd63", + "\ud83c\udfb3", + "\ud83e\udd4a", + "\ud83d\udc66", + "\ud83e\udde0", + "\ud83c\udde7\ud83c\uddf7", + "\ud83c\udf5e", + "\ud83e\udd31", + "\ud83e\uddf1", + "\ud83d\udc70\u200d\u2640\ufe0f", + "\ud83c\udf09", + "\ud83d\udcbc", + "\ud83c\uddee\ud83c\uddf4", + "\ud83c\uddfb\ud83c\uddec", + "\ud83e\udd66", + "\ud83d\udc94", + "\ud83e\uddf9", + "\ud83d\udfe4", + "\ud83e\udd0e", + "\ud83d\udfeb", + "\ud83c\udde7\ud83c\uddf3", + "\ud83e\uddcb", + "\ud83e\udee7", + "\ud83e\udea3", + "\ud83d\udc1b", + "\ud83c\udfd7\ufe0f", + "\ud83d\udca1", + "\ud83c\udde7\ud83c\uddec", + "\ud83d\ude85", + "\ud83d\ude84", + "\ud83c\udde7\ud83c\uddeb", + "\ud83c\udf2f", + "\ud83c\udde7\ud83c\uddee", + "\ud83d\ude8c", + "\ud83d\udd74\ufe0f", + "\ud83d\ude8f", + "\ud83d\udc64", + "\ud83d\udc65", + "\ud83e\uddc8", + "\ud83e\udd8b", + "\ud83c\udf35", + "\ud83c\udf70", + "\ud83d\udcc6", + "\ud83e\udd19", + "\ud83d\udcf2", + "\ud83c\uddf0\ud83c\udded", + "\ud83d\udc2b", + "\ud83d\udcf7", + "\ud83d\udcf8", + "\ud83c\udde8\ud83c\uddf2", + "\ud83c\udfd5\ufe0f", + "\ud83c\udde8\ud83c\udde6", + "\ud83c\uddee\ud83c\udde8", + "\u264b", + "\ud83d\udd6f\ufe0f", + "\ud83c\udf6c", + "\ud83e\udd6b", + "\ud83d\udef6", + "\ud83c\udde8\ud83c\uddfb", + "\ud83d\udd20", + "\u2651", + "\ud83d\ude97", + "\ud83d\uddc3\ufe0f", + "\ud83d\udcc7", + "\ud83d\uddc2\ufe0f", + "\ud83c\udde7\ud83c\uddf6", + "\ud83c\udfa0", + "\ud83e\ude9a", + "\ud83e\udd55", + "\ud83e\udd38", + "\ud83d\udc31", + "\ud83d\udc08", + "\ud83c\uddf0\ud83c\uddfe", + "\ud83d\udcbf", + "\ud83c\udde8\ud83c\uddeb", + "\ud83c\uddea\ud83c\udde6", + "\ud83c\uddf9\ud83c\udde9", + "\u26d3\ufe0f", + "\ud83e\ude91", + "\ud83c\udf7e", + "\ud83d\udcb9", + "\ud83d\udcc9", + "\ud83d\udcc8", + "\ud83c\udfc1", + "\ud83e\uddc0", + "\ud83c\udf52", + "\ud83c\udf38", + "\u265f\ufe0f", + "\ud83c\udf30", + "\ud83d\udc14", + "\ud83e\uddd2", + "\ud83d\udeb8", + "\ud83c\udde8\ud83c\uddf1", + "\ud83d\udc3f\ufe0f", + "\ud83c\udf6b", + "\ud83e\udd62", + "\ud83c\udde8\ud83c\uddfd", + "\ud83c\udf84", + "\u26ea", + "\ud83c\udfa6", + "\ud83c\udfaa", + "\ud83c\udf07", + "\ud83c\udf06", + "\ud83c\udfd9\ufe0f", + "\ud83c\udd91", + "\ud83d\udddc\ufe0f", + "\ud83d\udc4f", + "\ud83c\udfac", + "\ud83c\udfdb\ufe0f", + "\ud83e\uddd7", + "\ud83e\uddd7\u200d\u2642\ufe0f", + "\ud83e\uddd7\u200d\u2640\ufe0f", + "\ud83e\udd42", + "\ud83d\udccb", + "\ud83c\udde8\ud83c\uddf5", + "\ud83d\udd50", + "\ud83d\udd59", + "\ud83d\udd65", + "\ud83d\udd5a", + "\ud83d\udd66", + "\ud83d\udd5b", + "\ud83d\udd67", + "\ud83d\udd5c", + "\ud83d\udd51", + "\ud83d\udd5d", + "\ud83d\udd52", + "\ud83d\udd5e", + "\ud83d\udd53", + "\ud83d\udd5f", + "\ud83d\udd54", + "\ud83d\udd60", + "\ud83d\udd55", + "\ud83d\udd61", + "\ud83d\udd56", + "\ud83d\udd62", + "\ud83d\udd57", + "\ud83d\udd63", + "\ud83d\udd58", + "\ud83d\udd64", + "\ud83d\udcd5", + "\ud83d\udd10", + "\ud83c\udf02", + "\u2601\ufe0f", + "\ud83c\udf29\ufe0f", + "\u26c8\ufe0f", + "\ud83c\udf27\ufe0f", + "\ud83c\udf28\ufe0f", + "\ud83e\udd21", + "\u2663\ufe0f", + "\ud83c\udde8\ud83c\uddf3", + "\ud83e\udde5", + "\ud83e\udeb3", + "\ud83c\udf78", + "\ud83e\udd65", + "\ud83c\udde8\ud83c\udde8", + "\u2615", + "\u26b0\ufe0f", + "\ud83e\ude99", + "\ud83e\udd76", + "\ud83d\ude30", + "\ud83c\udde8\ud83c\uddf4", + "\u2604\ufe0f", + "\ud83c\uddf0\ud83c\uddf2", + "\ud83e\udded", + "\ud83d\udcbb", + "\ud83d\uddb1\ufe0f", + "\ud83c\udf8a", + "\ud83d\ude16", + "\ud83d\ude15", + "\ud83c\udde8\ud83c\uddec", + "\ud83c\udde8\ud83c\udde9", + "\u3297\ufe0f", + "\ud83d\udea7", + "\ud83d\udc77", + "\ud83d\udc77\u200d\u2642\ufe0f", + "\ud83d\udc77\u200d\u2640\ufe0f", + "\ud83c\udf9b\ufe0f", + "\ud83c\udfea", + "\ud83e\uddd1\u200d\ud83c\udf73", + "\ud83c\udde8\ud83c\uddf0", + "\ud83c\udf6a", + "\ud83c\udd92", + "\ud83d\udc6e", + "\u00a9\ufe0f", + "\ud83e\udeb8", + "\ud83c\udf3d", + "\ud83c\udde8\ud83c\uddf7", + "\ud83c\udde8\ud83c\uddee", + "\ud83d\udecb\ufe0f", + "\ud83d\udc6b", + "\ud83d\udc91", + "\ud83d\udc68\u200d\u2764\ufe0f\u200d\ud83d\udc68", + "\ud83d\udc69\u200d\u2764\ufe0f\u200d\ud83d\udc68", + "\ud83d\udc69\u200d\u2764\ufe0f\u200d\ud83d\udc69", + "\ud83d\udc8f", + "\ud83d\udc68\u200d\u2764\ufe0f\u200d\ud83d\udc8b\u200d\ud83d\udc68", + "\ud83d\udc69\u200d\u2764\ufe0f\u200d\ud83d\udc8b\u200d\ud83d\udc68", + "\ud83d\udc69\u200d\u2764\ufe0f\u200d\ud83d\udc8b\u200d\ud83d\udc69", + "\ud83d\udc2e", + "\ud83d\udc04", + "\ud83e\udd20", + "\ud83e\udd80", + "\ud83d\udd8d\ufe0f", + "\ud83d\udcb3", + "\ud83c\udf19", + "\ud83e\udd97", + "\ud83c\udfcf", + "\ud83c\udded\ud83c\uddf7", + "\ud83d\udc0a", + "\ud83e\udd50", + "\ud83e\udd1e", + "\ud83c\udf8c", + "\u2694\ufe0f", + "\ud83d\udc51", + "\ud83e\ude7c", + "\ud83d\ude22", + "\ud83d\ude3f", + "\ud83d\udd2e", + "\ud83c\udde8\ud83c\uddfa", + "\ud83e\udd52", + "\ud83e\udd64", + "\ud83e\uddc1", + "\ud83d\udc98", + "\ud83c\udde8\ud83c\uddfc", + "\ud83e\udd4c", + "\ud83d\udc68\u200d\ud83e\uddb1", + "\ud83d\udc69\u200d\ud83e\uddb1", + "\u27b0", + "\ud83d\udcb1", + "\ud83c\udf5b", + "\ud83e\udd2c", + "\ud83c\udf6e", + "\ud83d\udec3", + "\ud83e\udd69", + "\ud83c\udf00", + "\ud83c\udde8\ud83c\uddfe", + "\ud83c\udde8\ud83c\uddff", + "\ud83d\udde1\ufe0f", + "\ud83d\udc83", + "\ud83d\udc6f", + "\ud83d\udc6f\u200d\u2642\ufe0f", + "\ud83d\udc6f\u200d\u2640\ufe0f", + "\ud83c\udf61", + "\ud83d\udd76\ufe0f", + "\ud83c\udfaf", + "\ud83d\udca8", + "\ud83d\udcc5", + "\ud83c\udde9\ud83c\uddea", + "\ud83e\uddcf\u200d\u2642\ufe0f", + "\ud83e\uddcf", + "\ud83e\uddcf\u200d\u2640\ufe0f", + "\ud83c\udf33", + "\ud83e\udd8c", + "\ud83c\udde9\ud83c\uddf0", + "\ud83c\udfec", + "\ud83c\udfda\ufe0f", + "\ud83c\udfdc\ufe0f", + "\ud83c\udfdd\ufe0f", + "\ud83d\udda5\ufe0f", + "\ud83d\udd75\ufe0f", + "\ud83d\udca0", + "\u2666\ufe0f", + "\ud83c\udde9\ud83c\uddec", + "\ud83d\ude1e", + "\ud83d\ude25", + "\ud83e\udd78", + "\ud83e\udd3f", + "\ud83e\ude94", + "\ud83d\udcab", + "\ud83d\ude35", + "\ud83c\udde9\ud83c\uddef", + "\ud83e\uddec", + "\ud83d\udeaf", + "\ud83e\udda4", + "\ud83d\udc36", + "\ud83d\udc15", + "\ud83d\udcb5", + "\ud83c\udf8e", + "\ud83d\udc2c", + "\ud83c\udde9\ud83c\uddf2", + "\ud83c\udde9\ud83c\uddf4", + "\ud83e\udecf", + "\ud83d\udeaa", + "\ud83e\udee5", + "\ud83c\udf69", + "\ud83d\udd4a\ufe0f", + "\ud83d\udc09", + "\ud83d\udc32", + "\ud83d\udc57", + "\ud83d\udc2a", + "\ud83e\udd24", + "\ud83e\ude78", + "\ud83d\udca7", + "\ud83e\udd41", + "\ud83e\udd86", + "\ud83e\udd5f", + "\ud83d\udcc0", + "\ud83d\udce7", + "\ud83e\udd85", + "\ud83d\udc42", + "\ud83c\udf3e", + "\ud83e\uddbb", + "\ud83c\udf0d", + "\ud83c\udf0e", + "\ud83c\udf0f", + "\ud83c\uddea\ud83c\udde8", + "\ud83e\udd5a", + "\ud83c\udf46", + "\ud83c\uddea\ud83c\uddec", + "8\ufe0f\u20e3", + "\u2734\ufe0f", + "\u2733\ufe0f", + "\u23cf\ufe0f", + "\ud83c\uddf8\ud83c\uddfb", + "\ud83d\udd0c", + "\ud83d\udc18", + "\ud83d\uded7", + "\ud83e\udddd", + "\ud83e\udddd\u200d\u2642\ufe0f", + "\ud83e\udddd\u200d\u2640\ufe0f", + "\ud83e\udeb9", + "\ud83d\udd1a", + "\ud83c\udff4\udb40\udc67\udb40\udc62\udb40\udc65\udb40\udc6e\udb40\udc67\udb40\udc7f", + "\u2709\ufe0f", + "\ud83d\udce9", + "\ud83c\uddec\ud83c\uddf6", + "\ud83c\uddea\ud83c\uddf7", + "\ud83c\uddea\ud83c\uddf8", + "\ud83c\uddea\ud83c\uddea", + "\ud83c\uddea\ud83c\uddf9", + "\ud83c\uddea\ud83c\uddfa", + "\ud83d\udcb6", + "\ud83c\udff0", + "\ud83c\udfe4", + "\ud83c\udf32", + "\u2757", + "\ud83e\udd2f", + "\ud83d\ude11", + "\ud83d\udc41\ufe0f", + "\ud83d\udc41\ufe0f\u200d\ud83d\udde8\ufe0f", + "\ud83d\udc53", + "\ud83d\udc40", + "\ud83d\ude2e\u200d\ud83d\udca8", + "\ud83e\udd79", + "\ud83d\ude36\u200d\ud83c\udf2b\ufe0f", + "\ud83e\udee4", + "\ud83e\udd15", + "\ud83e\udee2", + "\ud83e\udee3", + "\ud83d\ude35\u200d\ud83d\udcab", + "\ud83e\udd12", + "\ud83e\udd26", + "\ud83d\udc4a", + "\ud83c\udfed", + "\ud83e\uddd1\u200d\ud83c\udfed", + "\ud83e\uddda", + "\ud83e\uddda\u200d\u2642\ufe0f", + "\ud83e\uddda\u200d\u2640\ufe0f", + "\ud83e\uddc6", + "\ud83c\uddeb\ud83c\uddf0", + "\ud83c\udf42", + "\ud83d\udc6a", + "\ud83d\udc68\u200d\ud83d\udc66", + "\ud83d\udc68\u200d\ud83d\udc66\u200d\ud83d\udc66", + "\ud83d\udc68\u200d\ud83d\udc67", + "\ud83d\udc68\u200d\ud83d\udc67\u200d\ud83d\udc66", + "\ud83d\udc68\u200d\ud83d\udc67\u200d\ud83d\udc67", + "\ud83d\udc68\u200d\ud83d\udc68\u200d\ud83d\udc66", + "\ud83d\udc68\u200d\ud83d\udc68\u200d\ud83d\udc66\u200d\ud83d\udc66", + "\ud83d\udc68\u200d\ud83d\udc68\u200d\ud83d\udc67", + "\ud83d\udc68\u200d\ud83d\udc68\u200d\ud83d\udc67\u200d\ud83d\udc66", + "\ud83d\udc68\u200d\ud83d\udc68\u200d\ud83d\udc67\u200d\ud83d\udc67", + "\ud83d\udc68\u200d\ud83d\udc69\u200d\ud83d\udc66", + "\ud83d\udc68\u200d\ud83d\udc69\u200d\ud83d\udc66\u200d\ud83d\udc66", + "\ud83d\udc68\u200d\ud83d\udc69\u200d\ud83d\udc67", + "\ud83d\udc68\u200d\ud83d\udc69\u200d\ud83d\udc67\u200d\ud83d\udc66", + "\ud83d\udc68\u200d\ud83d\udc69\u200d\ud83d\udc67\u200d\ud83d\udc67", + "\ud83d\udc69\u200d\ud83d\udc66", + "\ud83d\udc69\u200d\ud83d\udc66\u200d\ud83d\udc66", + "\ud83d\udc69\u200d\ud83d\udc67", + "\ud83d\udc69\u200d\ud83d\udc67\u200d\ud83d\udc66", + "\ud83d\udc69\u200d\ud83d\udc67\u200d\ud83d\udc67", + "\ud83d\udc69\u200d\ud83d\udc69\u200d\ud83d\udc66", + "\ud83d\udc69\u200d\ud83d\udc69\u200d\ud83d\udc66\u200d\ud83d\udc66", + "\ud83d\udc69\u200d\ud83d\udc69\u200d\ud83d\udc67", + "\ud83d\udc69\u200d\ud83d\udc69\u200d\ud83d\udc67\u200d\ud83d\udc66", + "\ud83d\udc69\u200d\ud83d\udc69\u200d\ud83d\udc67\u200d\ud83d\udc67", + "\ud83e\uddd1\u200d\ud83c\udf3e", + "\ud83c\uddeb\ud83c\uddf4", + "\u23e9", + "\ud83d\udce0", + "\ud83d\ude28", + "\ud83e\udeb6", + "\ud83d\udc3e", + "\ud83d\udd75\ufe0f\u200d\u2640\ufe0f", + "\u2640\ufe0f", + "\ud83c\udfa1", + "\u26f4\ufe0f", + "\ud83c\udfd1", + "\ud83c\uddeb\ud83c\uddef", + "\ud83d\uddc4\ufe0f", + "\ud83d\udcc1", + "\ud83d\udcfd\ufe0f", + "\ud83c\udf9e\ufe0f", + "\ud83c\uddeb\ud83c\uddee", + "\ud83d\udd25", + "\ud83d\ude92", + "\ud83e\uddef", + "\ud83e\udde8", + "\ud83e\uddd1\u200d\ud83d\ude92", + "\ud83c\udf86", + "\ud83c\udf13", + "\ud83c\udf1b", + "\ud83d\udc1f", + "\ud83c\udf65", + "\ud83c\udfa3", + "\u270a", + "\ud83e\udd1b", + "\ud83e\udd1c", + "5\ufe0f\u20e3", + "\ud83c\udf8f", + "\ud83e\udda9", + "\ud83d\udd26", + "\ud83e\udd7f", + "\ud83e\uded3", + "\u269c\ufe0f", + "\ud83d\udeec", + "\ud83d\udeeb", + "\ud83d\udcbe", + "\ud83c\udfb4", + "\ud83d\ude33", + "\ud83e\ude88", + "\ud83e\udeb0", + "\ud83e\udd4f", + "\ud83d\udef8", + "\ud83c\udf2b\ufe0f", + "\ud83c\udf01", + "\ud83e\udead", + "\ud83e\uded5", + "\ud83e\uddb6", + "\ud83c\udfc8", + "\ud83d\udc63", + "\ud83c\udf74", + "\ud83e\udd60", + "\u26f2", + "\ud83d\udd8b\ufe0f", + "4\ufe0f\u20e3", + "\ud83c\udf40", + "\ud83e\udd8a", + "\ud83c\uddeb\ud83c\uddf7", + "\ud83d\uddbc\ufe0f", + "\ud83c\udd93", + "\ud83c\uddec\ud83c\uddeb", + "\ud83c\uddf5\ud83c\uddeb", + "\ud83c\uddf9\ud83c\uddeb", + "\ud83c\udf73", + "\ud83c\udf64", + "\ud83c\udf5f", + "\ud83d\udc38", + "\ud83d\ude26", + "\u2639\ufe0f", + "\ud83d\ude4d\u200d\u2642\ufe0f", + "\ud83d\ude4d", + "\ud83d\ude4d\u200d\u2640\ufe0f", + "\ud83d\udd95", + "\u26fd", + "\ud83c\udf15", + "\ud83c\udf1d", + "\u26b1\ufe0f", + "\ud83c\uddec\ud83c\udde6", + "\ud83c\uddec\ud83c\uddf2", + "\ud83c\udfb2", + "\ud83e\uddc4", + "\ud83c\uddec\ud83c\udde7", + "\u2699\ufe0f", + "\ud83d\udc8e", + "\u264a", + "\ud83e\uddde", + "\ud83e\uddde\u200d\u2642\ufe0f", + "\ud83e\uddde\u200d\u2640\ufe0f", + "\ud83c\uddec\ud83c\uddea", + "\ud83c\uddec\ud83c\udded", + "\ud83d\udc7b", + "\ud83c\uddec\ud83c\uddee", + "\ud83c\udf81", + "\ud83d\udc9d", + "\ud83e\udeda", + "\ud83e\udd92", + "\ud83d\udc67", + "\ud83c\udf10", + "\ud83e\udde4", + "\ud83e\udd45", + "\ud83d\udc10", + "\ud83e\udd7d", + "\u26f3", + "\ud83c\udfcc\ufe0f", + "\ud83c\udfcc\ufe0f\u200d\u2642\ufe0f", + "\ud83c\udfcc\ufe0f\u200d\u2640\ufe0f", + "\ud83e\udebf", + "\ud83e\udd8d", + "\ud83c\udf47", + "\ud83c\uddec\ud83c\uddf7", + "\ud83c\udf4f", + "\ud83d\udcd7", + "\ud83d\udfe2", + "\ud83d\udc9a", + "\ud83e\udd57", + "\ud83d\udfe9", + "\ud83c\uddec\ud83c\uddf1", + "\ud83c\uddec\ud83c\udde9", + "\u2755", + "\ud83e\ude76", + "\u2754", + "\ud83d\ude2c", + "\ud83d\ude01", + "\ud83d\ude00", + "\ud83c\uddec\ud83c\uddf5", + "\ud83c\uddec\ud83c\uddfa", + "\ud83d\udc82", + "\ud83d\udc82\u200d\u2642\ufe0f", + "\ud83d\udc82\u200d\u2640\ufe0f", + "\ud83c\uddec\ud83c\uddf9", + "\ud83c\uddec\ud83c\uddec", + "\ud83e\uddae", + "\ud83c\uddec\ud83c\uddf3", + "\ud83c\uddec\ud83c\uddfc", + "\ud83c\udfb8", + "\ud83d\udd2b", + "\ud83c\uddec\ud83c\uddfe", + "\ud83e\udeae", + "\ud83d\udc87", + "\ud83d\udc87\u200d\u2642\ufe0f", + "\ud83d\udc87\u200d\u2640\ufe0f", + "\ud83c\udded\ud83c\uddf9", + "\ud83c\udf54", + "\ud83d\udd28", + "\u2692\ufe0f", + "\ud83d\udee0\ufe0f", + "\ud83e\udeac", + "\ud83d\udc39", + "\u270b", + "\ud83e\udd2d", + "\ud83e\udef0", + "\ud83d\udc5c", + "\ud83e\udd3e", + "\ud83e\udd1d", + "\ud83d\udca9", + "#\ufe0f\u20e3", + "\ud83d\udc25", + "\ud83d\udc23", + "\ud83c\udfa7", + "\ud83e\udea6", + "\ud83e\uddd1\u200d\u2695\ufe0f", + "\ud83d\ude49", + "\ud83c\udded\ud83c\uddf2", + "\u2764\ufe0f", + "\ud83d\udc9f", + "\ud83d\ude0d", + "\ud83d\ude3b", + "\ud83e\udef6", + "\u2764\ufe0f\u200d\ud83d\udd25", + "\ud83d\udc93", + "\ud83d\udc97", + "\u2665\ufe0f", + "\u2714\ufe0f", + "\u2797", + "\ud83d\udcb2", + "\ud83d\udff0", + "\u2763\ufe0f", + "\u2796", + "\u2716\ufe0f", + "\u2795", + "\ud83e\udd94", + "\ud83d\ude81", + "\ud83c\udf3f", + "\ud83c\udf3a", + "\ud83d\udd06", + "\ud83d\udc60", + "\ud83e\udd7e", + "\ud83d\uded5", + "\ud83e\udd9b", + "\ud83d\udd2a", + "\ud83d\udd73\ufe0f", + "\ud83c\udded\ud83c\uddf3", + "\ud83c\udf6f", + "\ud83c\udded\ud83c\uddf0", + "\ud83e\ude9d", + "\ud83d\udc34", + "\ud83c\udfc7", + "\ud83c\udfe5", + "\ud83e\udd75", + "\ud83c\udf36\ufe0f", + "\ud83c\udf2d", + "\ud83c\udfe8", + "\u2668\ufe0f", + "\u231b", + "\u23f3", + "\ud83c\udfe0", + "\ud83c\udfe1", + "\ud83c\udfd8\ufe0f", + "\ud83e\udd17", + "\ud83c\udded\ud83c\uddfa", + "\ud83d\ude2f", + "\ud83d\uded6", + "\ud83e\udebb", + "\ud83c\udf68", + "\ud83e\uddca", + "\ud83c\udfd2", + "\u26f8\ufe0f", + "\ud83c\udf66", + "\ud83c\uddee\ud83c\uddf8", + "\ud83c\udd94", + "\ud83e\udeaa", + "\ud83c\ude50", + "\ud83d\udc7f", + "\ud83d\udce5", + "\ud83d\udce8", + "\ud83e\udef5", + "\ud83c\uddee\ud83c\uddf3", + "\ud83c\uddee\ud83c\udde9", + "\u267e\ufe0f", + "\ud83d\udc81", + "\u2139\ufe0f", + "\ud83d\ude07", + "\u2049\ufe0f", + "\ud83d\udcf1", + "\ud83c\uddee\ud83c\uddf7", + "\ud83c\uddee\ud83c\uddf6", + "\ud83c\uddee\ud83c\uddea", + "\ud83c\uddee\ud83c\uddf2", + "\ud83c\uddee\ud83c\uddf1", + "\ud83c\uddee\ud83c\uddf9", + "\ud83c\udfee", + "\ud83c\udf83", + "\ud83c\uddef\ud83c\uddf2", + "\ud83d\uddfe", + "\ud83c\udfef", + "\ud83d\udc7a", + "\ud83d\udc79", + "\ud83e\uded9", + "\ud83d\udc56", + "\ud83e\udebc", + "\ud83c\uddef\ud83c\uddea", + "\ud83e\udde9", + "\ud83c\uddef\ud83c\uddf4", + "\ud83d\ude02", + "\ud83d\ude39", + "\ud83d\udd79\ufe0f", + "\ud83c\uddef\ud83c\uddf5", + "\ud83e\uddd1\u200d\u2696\ufe0f", + "\ud83e\udd39", + "\ud83d\udd4b", + "\ud83e\udd98", + "\ud83c\uddf0\ud83c\uddff", + "\ud83c\uddf0\ud83c\uddea", + "\ud83d\udd11", + "\u2328\ufe0f", + "\ud83d\udd1f", + "\ud83e\udeaf", + "\ud83d\udef4", + "\ud83d\udc58", + "\ud83c\uddf0\ud83c\uddee", + "\ud83d\udc8b", + "\ud83d\ude17", + "\ud83d\ude3d", + "\ud83d\ude1a", + "\ud83d\ude18", + "\ud83d\ude19", + "\ud83e\ude81", + "\ud83e\udd5d", + "\ud83e\uddce\u200d\u2642\ufe0f", + "\ud83e\uddce", + "\ud83e\uddce\u200d\u2640\ufe0f", + "\ud83e\udea2", + "\ud83d\udc28", + "\ud83c\ude01", + "\ud83c\uddfd\ud83c\uddf0", + "\ud83c\uddf0\ud83c\uddf7", + "\ud83c\uddf0\ud83c\uddfc", + "\ud83c\uddf0\ud83c\uddec", + "\ud83e\udd7c", + "\ud83c\udff7\ufe0f", + "\ud83e\udd4d", + "\ud83e\ude9c", + "\ud83d\udc1e", + "\ud83c\uddf1\ud83c\udde6", + "\ud83d\udd35", + "\ud83d\udd37", + "\ud83d\udd36", + "\ud83c\udf17", + "\ud83c\udf1c", + "\u271d\ufe0f", + "\ud83c\uddf1\ud83c\uddfb", + "\ud83d\ude06", + "\ud83e\udd6c", + "\ud83c\udf43", + "\ud83c\uddf1\ud83c\udde7", + "\ud83d\udcd2", + "\ud83d\udec5", + "\u2194\ufe0f", + "\ud83d\udde8\ufe0f", + "\u21a9\ufe0f", + "\ud83e\udef2", + "\ud83e\udef7", + "\ud83e\uddb5", + "\ud83c\udf4b", + "\u264c", + "\ud83d\udc06", + "\ud83c\uddf1\ud83c\uddf8", + "\ud83c\udf9a\ufe0f", + "\ud83c\uddf1\ud83c\uddf7", + "\u264e", + "\ud83c\uddf1\ud83c\uddfe", + "\ud83c\uddf1\ud83c\uddee", + "\ud83e\ude75", + "\ud83d\ude88", + "\ud83d\udd17", + "\ud83e\udd81", + "\ud83d\udc44", + "\ud83d\udc84", + "\ud83c\uddf1\ud83c\uddf9", + "\ud83e\udd8e", + "\ud83e\udd99", + "\ud83e\udd9e", + "\ud83d\udd12", + "\ud83d\udd0f", + "\ud83c\udf6d", + "\ud83e\ude98", + "\u27bf", + "\ud83e\uddf4", + "\ud83e\udeb7", + "\ud83e\uddd8", + "\ud83e\uddd8\u200d\u2642\ufe0f", + "\ud83e\uddd8\u200d\u2640\ufe0f", + "\ud83d\udd0a", + "\ud83d\udce2", + "\ud83c\udfe9", + "\ud83d\udc8c", + "\ud83e\udd1f", + "\ud83e\udeab", + "\ud83d\udd05", + "\ud83e\uddf3", + "\ud83e\udec1", + "\ud83c\uddf1\ud83c\uddfa", + "\ud83e\udd25", + "\u24c2\ufe0f", + "\ud83c\uddf2\ud83c\uddf4", + "\ud83c\uddf2\ud83c\uddf0", + "\ud83c\uddf2\ud83c\uddec", + "\ud83d\udd0d", + "\ud83d\udd0e", + "\ud83e\uddd9", + "\ud83e\uddd9\u200d\u2642\ufe0f", + "\ud83e\uddd9\u200d\u2640\ufe0f", + "\ud83e\ude84", + "\ud83e\uddf2", + "\ud83c\udc04", + "\ud83d\udceb", + "\ud83d\udcea", + "\ud83d\udcec", + "\ud83d\udced", + "\ud83c\uddf2\ud83c\uddfc", + "\ud83c\uddf2\ud83c\uddfe", + "\ud83c\uddf2\ud83c\uddfb", + "\ud83d\udd75\ufe0f\u200d\u2642\ufe0f", + "\u2642\ufe0f", + "\ud83c\uddf2\ud83c\uddf1", + "\ud83c\uddf2\ud83c\uddf9", + "\ud83e\udda3", + "\ud83d\udc68", + "\ud83d\udc68\u200d\ud83c\udfa8", + "\ud83d\udc68\u200d\ud83d\ude80", + "\ud83e\uddd4\u200d\u2642\ufe0f", + "\ud83e\udd38\u200d\u2642\ufe0f", + "\ud83d\udc68\u200d\ud83c\udf73", + "\ud83d\udd7a", + "\ud83e\udd26\u200d\u2642\ufe0f", + "\ud83d\udc68\u200d\ud83c\udfed", + "\ud83d\udc68\u200d\ud83c\udf3e", + "\ud83d\udc68\u200d\ud83c\udf7c", + "\ud83d\udc68\u200d\ud83d\ude92", + "\ud83d\udc68\u200d\u2695\ufe0f", + "\ud83d\udc68\u200d\ud83e\uddbd", + "\ud83d\udc68\u200d\ud83e\uddbc", + "\ud83e\udd35\u200d\u2642\ufe0f", + "\ud83d\udc68\u200d\u2696\ufe0f", + "\ud83e\udd39\u200d\u2642\ufe0f", + "\ud83d\udc68\u200d\ud83d\udd27", + "\ud83d\udc68\u200d\ud83d\udcbc", + "\ud83d\udc68\u200d\u2708\ufe0f", + "\ud83e\udd3e\u200d\u2642\ufe0f", + "\ud83e\udd3d\u200d\u2642\ufe0f", + "\ud83d\udc68\u200d\ud83d\udd2c", + "\ud83e\udd37\u200d\u2642\ufe0f", + "\ud83d\udc68\u200d\ud83c\udfa4", + "\ud83d\udc68\u200d\ud83c\udf93", + "\ud83d\udc68\u200d\ud83c\udfeb", + "\ud83d\udc68\u200d\ud83d\udcbb", + "\ud83d\udc72", + "\ud83d\udc68\u200d\ud83e\uddaf", + "\ud83d\udc73\u200d\u2642\ufe0f", + "\ud83d\udc70\u200d\u2642\ufe0f", + "\ud83c\udf4a", + "\ud83e\udd6d", + "\ud83d\udc5e", + "\ud83d\udd70\ufe0f", + "\ud83e\uddbd", + "\ud83c\udf41", + "\ud83e\ude87", + "\ud83c\uddf2\ud83c\udded", + "\ud83e\udd4b", + "\ud83c\uddf2\ud83c\uddf6", + "\ud83d\ude37", + "\ud83d\udc86", + "\ud83d\udc86\u200d\u2642\ufe0f", + "\ud83d\udc86\u200d\u2640\ufe0f", + "\ud83e\uddc9", + "\ud83c\uddf2\ud83c\uddf7", + "\ud83c\uddf2\ud83c\uddfa", + "\ud83c\uddfe\ud83c\uddf9", + "\ud83c\udf56", + "\ud83e\uddd1\u200d\ud83d\udd27", + "\ud83e\uddbe", + "\ud83e\uddbf", + "\ud83c\udf96\ufe0f", + "\ud83c\udfc5", + "\u2695\ufe0f", + "\ud83d\udce3", + "\ud83c\udf48", + "\ud83e\udee0", + "\ud83d\udcdd", + "\ud83e\udd3c\u200d\u2642\ufe0f", + "\u2764\ufe0f\u200d\ud83e\ude79", + "\ud83d\udd4e", + "\ud83d\udeb9", + "\ud83e\udddc\u200d\u2640\ufe0f", + "\ud83e\udddc\u200d\u2642\ufe0f", + "\ud83e\udddc", + "\ud83e\udd18", + "\ud83d\ude87", + "\ud83c\uddf2\ud83c\uddfd", + "\ud83e\udda0", + "\ud83c\uddeb\ud83c\uddf2", + "\ud83c\udfa4", + "\ud83d\udd2c", + "\ud83e\ude96", + "\ud83e\udd5b", + "\ud83c\udf0c", + "\ud83d\ude90", + "\ud83d\udcbd", + "\ud83e\ude9e", + "\ud83e\udea9", + "\ud83d\udcf4", + "\ud83c\uddf2\ud83c\udde9", + "\ud83c\uddf2\ud83c\udde8", + "\ud83e\udd11", + "\ud83d\udcb8", + "\ud83d\udcb0", + "\ud83c\uddf2\ud83c\uddf3", + "\ud83d\udc12", + "\ud83d\udc35", + "\ud83e\uddd0", + "\ud83d\ude9d", + "\ud83c\uddf2\ud83c\uddea", + "\ud83c\uddf2\ud83c\uddf8", + "\ud83c\udf14", + "\ud83e\udd6e", + "\ud83e\udece", + "\ud83c\uddf2\ud83c\udde6", + "\ud83c\udf93", + "\ud83d\udd4c", + "\ud83e\udd9f", + "\ud83d\udee5\ufe0f", + "\ud83d\udef5", + "\ud83c\udfcd\ufe0f", + "\ud83e\uddbc", + "\ud83d\udee3\ufe0f", + "\ud83d\uddfb", + "\u26f0\ufe0f", + "\ud83d\udeb5", + "\ud83d\udeb5\u200d\u2642\ufe0f", + "\ud83d\udeb5\u200d\u2640\ufe0f", + "\ud83d\udea0", + "\ud83d\ude9e", + "\ud83c\udfd4\ufe0f", + "\ud83d\udc2d", + "\ud83d\udc01", + "\ud83e\udea4", + "\ud83c\udfa5", + "\ud83d\uddff", + "\ud83c\uddf2\ud83c\uddff", + "\ud83e\udd36", + "\ud83d\udcaa", + "\ud83c\udf44", + "\ud83c\udfb9", + "\ud83c\udfb5", + "\ud83c\udfbc", + "\ud83d\udd07", + "\ud83e\uddd1\u200d\ud83c\udf84", + "\ud83c\uddf2\ud83c\uddf2", + "\ud83d\udc85", + "\ud83d\udcdb", + "\ud83c\uddf3\ud83c\udde6", + "\ud83c\udfde\ufe0f", + "\ud83c\uddf3\ud83c\uddf7", + "\ud83e\udd22", + "\ud83e\uddff", + "\ud83d\udc54", + "\u274e", + "\ud83c\uddf3\ud83c\uddf5", + "\ud83e\udd13", + "\ud83e\udeba", + "\ud83e\ude86", + "\ud83c\uddf3\ud83c\uddf1", + "\ud83d\ude10", + "\ud83c\udd95", + "\ud83c\uddf3\ud83c\udde8", + "\ud83c\udf11", + "\ud83c\udf1a", + "\ud83c\uddf3\ud83c\uddff", + "\ud83d\udcf0", + "\ud83d\uddde\ufe0f", + "\u23ed\ufe0f", + "\ud83c\udd96", + "\ud83d\ude45\u200d\u2642\ufe0f", + "\ud83d\ude45\u200d\u2640\ufe0f", + "\ud83c\uddf3\ud83c\uddee", + "\ud83c\uddf3\ud83c\uddea", + "\ud83c\uddf3\ud83c\uddec", + "\ud83c\udf03", + "9\ufe0f\u20e3", + "\ud83e\udd77", + "\ud83c\uddf3\ud83c\uddfa", + "\ud83d\udd15", + "\ud83d\udeb3", + "\u26d4", + "\ud83d\udeab", + "\ud83d\ude45", + "\ud83d\udcf5", + "\ud83d\ude36", + "\ud83d\udeb7", + "\ud83d\udead", + "\ud83d\udeb1", + "\ud83c\uddf3\ud83c\uddeb", + "\ud83c\uddf0\ud83c\uddf5", + "\ud83c\uddf2\ud83c\uddf5", + "\ud83c\uddf3\ud83c\uddf4", + "\ud83d\udc43", + "\ud83d\udcd3", + "\ud83d\udcd4", + "\ud83c\udfb6", + "\ud83d\udd29", + "\u2b55", + "\ud83c\udd7e\ufe0f", + "\ud83c\udf0a", + "\ud83d\udc19", + "\ud83c\udf62", + "\ud83c\udfe2", + "\ud83e\uddd1\u200d\ud83d\udcbc", + "\ud83d\udee2\ufe0f", + "\ud83c\udd97", + "\ud83d\udc4c", + "\ud83d\ude46\u200d\u2642\ufe0f", + "\ud83d\ude46", + "\ud83d\ude46\u200d\u2640\ufe0f", + "\ud83d\udddd\ufe0f", + "\ud83e\uddd3", + "\ud83d\udc74", + "\ud83d\udc75", + "\ud83e\uded2", + "\ud83d\udd49\ufe0f", + "\ud83c\uddf4\ud83c\uddf2", + "\ud83d\udd1b", + "\ud83d\ude98", + "\ud83d\ude8d", + "\ud83d\ude94", + "\ud83d\ude96", + "1\ufe0f\u20e3", + "\ud83e\ude71", + "\ud83e\uddc5", + "\ud83d\udcc2", + "\ud83d\udc50", + "\ud83d\ude2e", + "\u2602\ufe0f", + "\u26ce", + "\ud83d\udcd9", + "\ud83d\udfe0", + "\ud83e\udde1", + "\ud83d\udfe7", + "\ud83e\udda7", + "\u2626\ufe0f", + "\ud83e\udda6", + "\ud83d\udce4", + "\ud83e\udd89", + "\ud83d\udc02", + "\ud83e\uddaa", + "\ud83d\udce6", + "\ud83d\udcc4", + "\ud83d\udcc3", + "\ud83d\udcdf", + "\ud83d\udd8c\ufe0f", + "\ud83c\uddf5\ud83c\uddf0", + "\ud83c\uddf5\ud83c\uddfc", + "\ud83c\uddf5\ud83c\uddf8", + "\ud83e\udef3", + "\ud83c\udf34", + "\ud83e\udef4", + "\ud83e\udd32", + "\ud83c\uddf5\ud83c\udde6", + "\ud83e\udd5e", + "\ud83d\udc3c", + "\ud83d\udcce", + "\ud83d\udd87\ufe0f", + "\ud83c\uddf5\ud83c\uddec", + "\ud83e\ude82", + "\ud83c\uddf5\ud83c\uddfe", + "\u26f1\ufe0f", + "\ud83c\udd7f\ufe0f", + "\ud83e\udd9c", + "\u303d\ufe0f", + "\u26c5", + "\ud83c\udf89", + "\ud83e\udd73", + "\ud83d\udef3\ufe0f", + "\ud83d\udec2", + "\u23f8\ufe0f", + "\ud83e\udedb", + "\u262e\ufe0f", + "\ud83c\udf51", + "\ud83e\udd9a", + "\ud83e\udd5c", + "\ud83c\udf50", + "\ud83d\udd8a\ufe0f", + "\u270f\ufe0f", + "\ud83d\udc27", + "\ud83d\ude14", + "\ud83e\uddd1\u200d\ud83e\udd1d\u200d\ud83e\uddd1", + "\ud83e\udec2", + "\ud83c\udfad", + "\ud83d\ude23", + "\ud83e\uddd1\u200d\ud83e\uddb2", + "\ud83e\uddd1\u200d\ud83e\uddb1", + "\ud83e\uddd1\u200d\ud83c\udf7c", + "\ud83e\udd3a", + "\ud83e\uddd1\u200d\ud83e\uddbd", + "\ud83e\uddd1\u200d\ud83e\uddbc", + "\ud83e\udd35", + "\ud83e\uddd1\u200d\ud83e\uddb0", + "\ud83e\uddd1\u200d\ud83e\uddb3", + "\ud83e\udec5", + "\ud83e\uddd1\u200d\ud83e\uddaf", + "\ud83d\udc73", + "\ud83d\udc70", + "\ud83c\uddf5\ud83c\uddea", + "\ud83e\uddeb", + "\ud83c\uddf5\ud83c\udded", + "\u260e\ufe0f", + "\u26cf\ufe0f", + "\ud83d\udefb", + "\ud83e\udd67", + "\ud83d\udc37", + "\ud83d\udc16", + "\ud83d\udc3d", + "\ud83d\udc8a", + "\ud83e\uddd1\u200d\u2708\ufe0f", + "\ud83e\ude85", + "\ud83e\udd0c", + "\ud83e\udd0f", + "\ud83c\udf4d", + "\ud83c\udfd3", + "\ud83e\ude77", + "\ud83c\udff4\u200d\u2620\ufe0f", + "\u2653", + "\ud83c\uddf5\ud83c\uddf3", + "\ud83c\udf55", + "\ud83e\udea7", + "\ud83d\uded0", + "\ud83c\udf7d\ufe0f", + "\u23ef\ufe0f", + "\ud83d\udedd", + "\ud83e\udd7a", + "\ud83e\udea0", + "\ud83d\udc47", + "\ud83d\udc48", + "\ud83d\udc49", + "\u261d\ufe0f", + "\ud83d\udc46", + "\ud83c\uddf5\ud83c\uddf1", + "\ud83d\udc3b\u200d\u2744\ufe0f", + "\ud83d\ude93", + "\ud83d\udc6e\u200d\u2642\ufe0f", + "\ud83d\udc6e\u200d\u2640\ufe0f", + "\ud83d\udc29", + "\ud83c\udf7f", + "\ud83c\uddf5\ud83c\uddf9", + "\ud83c\udfe3", + "\ud83d\udcef", + "\ud83d\udcee", + "\ud83d\udeb0", + "\ud83e\udd54", + "\ud83e\udeb4", + "\ud83d\udc5d", + "\ud83c\udf57", + "\ud83d\udcb7", + "\ud83e\uded7", + "\ud83d\ude21", + "\ud83d\ude3e", + "\ud83d\ude4e", + "\ud83d\ude4e\u200d\u2642\ufe0f", + "\ud83d\ude4e\u200d\u2640\ufe0f", + "\ud83d\ude4f", + "\ud83d\udcff", + "\ud83e\udec3", + "\ud83e\udec4", + "\ud83e\udd30", + "\ud83e\udd68", + "\u23ee\ufe0f", + "\ud83e\udd34", + "\ud83d\udc78", + "\ud83d\udda8\ufe0f", + "\ud83e\uddaf", + "\ud83c\uddf5\ud83c\uddf7", + "\ud83e\udd2e", + "\ud83d\udfe3", + "\ud83d\udc9c", + "\ud83d\udfea", + "\ud83d\udc5b", + "\ud83d\udccc", + "\ud83d\udeae", + "\ud83c\uddf6\ud83c\udde6", + "\u2753", + "\ud83d\udc30", + "\ud83d\udc07", + "\ud83e\udd9d", + "\ud83d\udc0e", + "\ud83c\udfce\ufe0f", + "\ud83d\udcfb", + "\ud83d\udd18", + "\u2622\ufe0f", + "\ud83d\ude83", + "\ud83d\udee4\ufe0f", + "\ud83c\udf08", + "\ud83c\udff3\ufe0f\u200d\ud83c\udf08", + "\ud83e\udd1a", + "\ud83e\udd28", + "\ud83d\udd90\ufe0f", + "\ud83d\ude4c", + "\ud83d\ude4b", + "\ud83d\ude4b\u200d\u2642\ufe0f", + "\ud83d\ude4b\u200d\u2640\ufe0f", + "\ud83d\udc0f", + "\ud83c\udf5c", + "\ud83d\udc00", + "\ud83e\ude92", + "\ud83e\uddfe", + "\u23fa\ufe0f", + "\u267b\ufe0f", + "\ud83d\udd34", + "\ud83e\udde7", + "\ud83d\udc68\u200d\ud83e\uddb0", + "\ud83d\udc69\u200d\ud83e\uddb0", + "\ud83d\udfe5", + "\u00ae\ufe0f", + "\u263a\ufe0f", + "\ud83d\ude0c", + "\ud83c\udf97\ufe0f", + "\ud83d\udd01", + "\ud83d\udd02", + "\u26d1\ufe0f", + "\ud83d\udebb", + "\ud83c\uddf7\ud83c\uddea", + "\ud83d\udc9e", + "\u23ea", + "\ud83e\udd8f", + "\ud83c\udf80", + "\ud83c\udf5a", + "\ud83c\udf59", + "\ud83c\udf58", + "\ud83c\udf91", + "\ud83d\uddef\ufe0f", + "\ud83e\udef1", + "\ud83e\udef8", + "\ud83d\udc8d", + "\ud83d\udedf", + "\ud83e\ude90", + "\ud83e\udd16", + "\ud83e\udea8", + "\ud83d\ude80", + "\ud83e\udd23", + "\ud83d\ude44", + "\ud83e\uddfb", + "\ud83c\udfa2", + "\ud83d\udefc", + "\ud83c\uddf7\ud83c\uddf4", + "\ud83d\udc13", + "\ud83c\udf39", + "\ud83c\udff5\ufe0f", + "\ud83d\udea8", + "\ud83d\udccd", + "\ud83d\udea3", + "\ud83d\udea3\u200d\u2642\ufe0f", + "\ud83d\udea3\u200d\u2640\ufe0f", + "\ud83c\uddf7\ud83c\uddfa", + "\ud83c\udfc9", + "\ud83c\udfc3", + "\ud83c\udfc3\u200d\u2642\ufe0f", + "\ud83c\udfbd", + "\ud83c\udfc3\u200d\u2640\ufe0f", + "\ud83c\uddf7\ud83c\uddfc", + "\ud83c\ude02\ufe0f", + "\ud83e\uddf7", + "\ud83e\uddba", + "\u2650", + "\ud83c\udf76", + "\ud83e\uddc2", + "\ud83e\udee1", + "\ud83c\uddfc\ud83c\uddf8", + "\ud83c\uddf8\ud83c\uddf2", + "\ud83d\udc61", + "\ud83e\udd6a", + "\ud83c\udf85", + "\ud83c\uddf8\ud83c\uddf9", + "\ud83e\udd7b", + "\ud83d\udc81\u200d\u2642\ufe0f", + "\ud83d\udc81\u200d\u2640\ufe0f", + "\ud83d\udce1", + "\ud83c\uddf8\ud83c\udde6", + "\ud83e\uddd6\u200d\u2642\ufe0f", + "\ud83e\uddd6", + "\ud83e\uddd6\u200d\u2640\ufe0f", + "\ud83e\udd95", + "\ud83c\udfb7", + "\ud83e\udde3", + "\ud83c\udfeb", + "\ud83c\udf92", + "\ud83e\uddd1\u200d\ud83d\udd2c", + "\u2702\ufe0f", + "\ud83e\udd82", + "\u264f", + "\ud83c\udff4\udb40\udc67\udb40\udc62\udb40\udc73\udb40\udc63\udb40\udc74\udb40\udc7f", + "\ud83d\ude31", + "\ud83d\ude40", + "\ud83e\ude9b", + "\ud83d\udcdc", + "\ud83e\uddad", + "\ud83d\udcba", + "\u3299\ufe0f", + "\ud83d\ude48", + "\ud83c\udf31", + "\ud83e\udd33", + "\ud83c\uddf8\ud83c\uddf3", + "\ud83c\uddf7\ud83c\uddf8", + "\ud83d\udc15\u200d\ud83e\uddba", + "7\ufe0f\u20e3", + "\ud83e\udea1", + "\ud83c\uddf8\ud83c\udde8", + "\ud83e\udee8", + "\ud83e\udd58", + "\u2618\ufe0f", + "\ud83e\udd88", + "\ud83c\udf67", + "\ud83d\udc11", + "\ud83d\udc1a", + "\ud83d\udee1\ufe0f", + "\u26e9\ufe0f", + "\ud83d\udea2", + "\ud83d\udc55", + "\ud83d\udecd\ufe0f", + "\ud83d\uded2", + "\ud83e\ude73", + "\ud83d\udebf", + "\ud83e\udd90", + "\ud83e\udd37", + "\ud83e\udd2b", + "\ud83c\uddf8\ud83c\uddf1", + "\ud83d\udcf6", + "\ud83c\uddf8\ud83c\uddec", + "\ud83e\uddd1\u200d\ud83c\udfa4", + "\ud83c\uddf8\ud83c\uddfd", + "6\ufe0f\u20e3", + "\ud83d\udd2f", + "\ud83d\udef9", + "\ud83c\udfbf", + "\u26f7\ufe0f", + "\ud83d\udc80", + "\u2620\ufe0f", + "\ud83e\udda8", + "\ud83d\udef7", + "\ud83d\ude34", + "\ud83d\udecc", + "\ud83d\ude2a", + "\ud83d\ude41", + "\ud83d\ude42", + "\ud83c\udfb0", + "\ud83e\udda5", + "\ud83c\uddf8\ud83c\uddf0", + "\ud83c\uddf8\ud83c\uddee", + "\ud83d\udee9\ufe0f", + "\ud83d\udd39", + "\ud83d\udd38", + "\ud83d\udd3a", + "\ud83d\udd3b", + "\ud83d\ude04", + "\ud83d\ude38", + "\ud83d\ude03", + "\ud83d\ude3a", + "\ud83e\udd72", + "\ud83e\udd70", + "\ud83d\ude08", + "\ud83d\ude0f", + "\ud83d\ude3c", + "\ud83d\udeac", + "\ud83d\udc0c", + "\ud83d\udc0d", + "\ud83e\udd27", + "\ud83c\udfc2", + "\u2744\ufe0f", + "\u26c4", + "\u2603\ufe0f", + "\ud83e\uddfc", + "\ud83d\ude2d", + "\u26bd", + "\ud83e\udde6", + "\ud83e\udd4e", + "\ud83c\uddf8\ud83c\udde7", + "\ud83c\uddf8\ud83c\uddf4", + "\ud83d\udd1c", + "\ud83c\udd98", + "\ud83d\udd09", + "\ud83c\uddff\ud83c\udde6", + "\ud83c\uddec\ud83c\uddf8", + "\ud83c\uddf8\ud83c\uddf8", + "\ud83d\udc7e", + "\u2660\ufe0f", + "\ud83c\udf5d", + "\u2747\ufe0f", + "\ud83c\udf87", + "\u2728", + "\ud83d\udc96", + "\ud83d\ude4a", + "\ud83d\udd08", + "\ud83d\udde3\ufe0f", + "\ud83d\udcac", + "\ud83d\udea4", + "\ud83d\udd77\ufe0f", + "\ud83d\udd78\ufe0f", + "\ud83d\uddd3\ufe0f", + "\ud83d\uddd2\ufe0f", + "\ud83e\uddfd", + "\ud83e\udd44", + "\ud83e\udd91", + "\ud83c\uddf1\ud83c\uddf0", + "\ud83c\udde7\ud83c\uddf1", + "\ud83c\uddf8\ud83c\udded", + "\ud83c\uddf0\ud83c\uddf3", + "\ud83c\uddf1\ud83c\udde8", + "\ud83c\uddf2\ud83c\uddeb", + "\ud83c\uddf5\ud83c\uddf2", + "\ud83c\uddfb\ud83c\udde8", + "\ud83c\udfdf\ufe0f", + "\ud83e\uddcd\u200d\u2642\ufe0f", + "\ud83e\uddcd", + "\ud83e\uddcd\u200d\u2640\ufe0f", + "\u2b50", + "\ud83c\udf1f", + "\u262a\ufe0f", + "\u2721\ufe0f", + "\ud83e\udd29", + "\ud83c\udf20", + "\ud83d\ude89", + "\ud83d\uddfd", + "\ud83d\ude82", + "\ud83e\ude7a", + "\ud83c\udf72", + "\u23f9\ufe0f", + "\ud83d\uded1", + "\u23f1\ufe0f", + "\ud83d\udccf", + "\ud83c\udf53", + "\ud83d\ude1b", + "\ud83d\ude1d", + "\ud83d\ude1c", + "\ud83e\uddd1\u200d\ud83c\udf93", + "\ud83c\udf99\ufe0f", + "\ud83e\udd59", + "\ud83c\uddf8\ud83c\udde9", + "\ud83c\udf25\ufe0f", + "\ud83c\udf26\ufe0f", + "\ud83c\udf24\ufe0f", + "\ud83c\udf1e", + "\ud83c\udf3b", + "\ud83d\ude0e", + "\u2600\ufe0f", + "\ud83c\udf05", + "\ud83c\udf04", + "\ud83e\uddb8", + "\ud83e\uddb8\u200d\u2642\ufe0f", + "\ud83e\uddb8\u200d\u2640\ufe0f", + "\ud83e\uddb9", + "\ud83e\uddb9\u200d\u2642\ufe0f", + "\ud83e\uddb9\u200d\u2640\ufe0f", + "\ud83c\udfc4", + "\ud83c\udfc4\u200d\u2642\ufe0f", + "\ud83c\udfc4\u200d\u2640\ufe0f", + "\ud83c\uddf8\ud83c\uddf7", + "\ud83c\udf63", + "\ud83d\ude9f", + "\ud83c\uddf8\ud83c\uddef", + "\ud83e\udda2", + "\ud83c\uddf8\ud83c\uddff", + "\ud83d\ude13", + "\ud83d\udca6", + "\ud83d\ude05", + "\ud83c\uddf8\ud83c\uddea", + "\ud83c\udf60", + "\ud83e\ude72", + "\ud83c\udfca", + "\ud83c\udfca\u200d\u2642\ufe0f", + "\ud83c\udfca\u200d\u2640\ufe0f", + "\ud83c\udde8\ud83c\udded", + "\ud83d\udd23", + "\ud83d\udd4d", + "\ud83c\uddf8\ud83c\uddfe", + "\ud83d\udc89", + "\ud83e\udd96", + "\ud83c\udf2e", + "\ud83c\uddf9\ud83c\uddfc", + "\ud83c\uddf9\ud83c\uddef", + "\ud83e\udd61", + "\ud83e\uded4", + "\ud83c\udf8b", + "\ud83c\uddf9\ud83c\uddff", + "\u2649", + "\ud83d\ude95", + "\ud83c\udf75", + "\ud83e\uddd1\u200d\ud83c\udfeb", + "\ud83e\uded6", + "\ud83e\uddd1\u200d\ud83d\udcbb", + "\ud83e\uddf8", + "\ud83d\udcde", + "\ud83d\udd2d", + "\ud83c\udfbe", + "\u26fa", + "\ud83e\uddea", + "\ud83c\uddf9\ud83c\udded", + "\ud83c\udf21\ufe0f", + "\ud83e\udd14", + "\ud83e\ude74", + "\ud83d\udcad", + "\ud83e\uddf5", + "3\ufe0f\u20e3", + "\ud83c\udfab", + "\ud83c\udf9f\ufe0f", + "\ud83d\udc2f", + "\ud83d\udc05", + "\u23f2\ufe0f", + "\ud83c\uddf9\ud83c\uddf1", + "\ud83d\ude2b", + "\u2122\ufe0f", + "\ud83c\uddf9\ud83c\uddec", + "\ud83d\udebd", + "\ud83c\uddf9\ud83c\uddf0", + "\ud83d\uddfc", + "\ud83c\udf45", + "\ud83c\uddf9\ud83c\uddf4", + "\ud83d\udc45", + "\ud83e\uddf0", + "\ud83e\uddb7", + "\ud83e\udea5", + "\ud83d\udd1d", + "\ud83c\udfa9", + "\ud83c\udf2a\ufe0f", + "\ud83c\uddf9\ud83c\uddf7", + "\ud83d\uddb2\ufe0f", + "\ud83d\ude9c", + "\ud83d\udea5", + "\ud83d\ude8b", + "\ud83d\ude86", + "\ud83d\ude8a", + "\ud83c\udff3\ufe0f\u200d\u26a7\ufe0f", + "\u26a7\ufe0f", + "\ud83d\udea9", + "\ud83d\udcd0", + "\ud83d\udd31", + "\ud83c\uddf9\ud83c\uddf9", + "\ud83c\uddf9\ud83c\udde6", + "\ud83d\ude24", + "\ud83e\uddcc", + "\ud83d\ude8e", + "\ud83c\udfc6", + "\ud83c\udf79", + "\ud83d\udc20", + "\ud83d\ude9a", + "\ud83c\udfba", + "\ud83c\udf37", + "\ud83e\udd43", + "\ud83c\uddf9\ud83c\uddf3", + "\ud83e\udd83", + "\ud83c\uddf9\ud83c\uddf2", + "\ud83c\uddf9\ud83c\udde8", + "\ud83d\udc22", + "\ud83c\uddf9\ud83c\uddfb", + "\ud83d\udcfa", + "\ud83d\udd00", + "2\ufe0f\u20e3", + "\ud83d\udc95", + "\ud83d\udc6c", + "\ud83d\udc6d", + "\ud83c\ude39", + "\ud83c\ude34", + "\ud83c\ude3a", + "\ud83c\ude2f", + "\ud83c\ude37\ufe0f", + "\ud83c\ude36", + "\ud83c\ude35", + "\ud83c\ude1a", + "\ud83c\ude38", + "\ud83c\ude32", + "\ud83c\ude33", + "\ud83c\uddfa\ud83c\uddec", + "\ud83c\uddfa\ud83c\udde6", + "\u2614", + "\ud83d\ude12", + "\ud83d\udd1e", + "\ud83e\udd84", + "\ud83c\udde6\ud83c\uddea", + "\ud83c\uddfa\ud83c\uddf3", + "\ud83d\udd13", + "\ud83c\udd99", + "\ud83d\ude43", + "\ud83c\uddfa\ud83c\uddfe", + "\ud83c\uddfa\ud83c\uddf8", + "\ud83c\uddfa\ud83c\uddf2", + "\ud83c\uddfb\ud83c\uddee", + "\ud83c\uddfa\ud83c\uddff", + "\u270c\ufe0f", + "\ud83e\udddb", + "\ud83e\udddb\u200d\u2642\ufe0f", + "\ud83e\udddb\u200d\u2640\ufe0f", + "\ud83c\uddfb\ud83c\uddfa", + "\ud83c\uddfb\ud83c\udde6", + "\ud83c\uddfb\ud83c\uddea", + "\ud83d\udea6", + "\ud83d\udcfc", + "\ud83d\udcf3", + "\ud83d\udcf9", + "\ud83c\udfae", + "\ud83c\uddfb\ud83c\uddf3", + "\ud83c\udfbb", + "\u264d", + "\ud83c\udf0b", + "\ud83c\udfd0", + "\ud83c\udd9a", + "\ud83d\udd96", + "\ud83e\uddc7", + "\ud83c\udff4\udb40\udc67\udb40\udc62\udb40\udc77\udb40\udc6c\udb40\udc73\udb40\udc7f", + "\ud83d\udeb6", + "\ud83d\udeb6\u200d\u2642\ufe0f", + "\ud83d\udeb6\u200d\u2640\ufe0f", + "\ud83c\uddfc\ud83c\uddeb", + "\ud83c\udf18", + "\ud83c\udf16", + "\u26a0\ufe0f", + "\ud83d\uddd1\ufe0f", + "\u231a", + "\ud83d\udc03", + "\ud83e\udd3d", + "\ud83c\udf49", + "\ud83d\udc4b", + "\u3030\ufe0f", + "\ud83c\udf12", + "\ud83d\udebe", + "\ud83d\ude29", + "\ud83d\udc92", + "\ud83c\udfcb\ufe0f", + "\ud83c\udfcb\ufe0f\u200d\u2642\ufe0f", + "\ud83c\udfcb\ufe0f\u200d\u2640\ufe0f", + "\ud83c\uddea\ud83c\udded", + "\ud83d\udc33", + "\ud83d\udc0b", + "\ud83d\udede", + "\u2638\ufe0f", + "\u267f", + "\u2705", + "\u26aa", + "\ud83c\udff3\ufe0f", + "\ud83d\udcae", + "\ud83d\udc68\u200d\ud83e\uddb3", + "\ud83d\udc69\u200d\ud83e\uddb3", + "\ud83e\udd0d", + "\u2b1c", + "\u25fd", + "\u25fb\ufe0f", + "\u25ab\ufe0f", + "\ud83d\udd33", + "\ud83e\udd40", + "\ud83c\udf90", + "\ud83c\udf2c\ufe0f", + "\ud83e\ude9f", + "\ud83c\udf77", + "\ud83e\udebd", + "\ud83d\ude09", + "\ud83d\udedc", + "\ud83d\udc3a", + "\ud83d\udc69", + "\ud83d\udc69\u200d\ud83c\udfa8", + "\ud83d\udc69\u200d\ud83d\ude80", + "\ud83e\uddd4\u200d\u2640\ufe0f", + "\ud83e\udd38\u200d\u2640\ufe0f", + "\ud83d\udc69\u200d\ud83c\udf73", + "\ud83e\udd26\u200d\u2640\ufe0f", + "\ud83d\udc69\u200d\ud83c\udfed", + "\ud83d\udc69\u200d\ud83c\udf3e", + "\ud83d\udc69\u200d\ud83c\udf7c", + "\ud83d\udc69\u200d\ud83d\ude92", + "\ud83d\udc69\u200d\u2695\ufe0f", + "\ud83d\udc69\u200d\ud83e\uddbd", + "\ud83d\udc69\u200d\ud83e\uddbc", + "\ud83e\udd35\u200d\u2640\ufe0f", + "\ud83d\udc69\u200d\u2696\ufe0f", + "\ud83e\udd39\u200d\u2640\ufe0f", + "\ud83d\udc69\u200d\ud83d\udd27", + "\ud83d\udc69\u200d\ud83d\udcbc", + "\ud83d\udc69\u200d\u2708\ufe0f", + "\ud83e\udd3e\u200d\u2640\ufe0f", + "\ud83e\udd3d\u200d\u2640\ufe0f", + "\ud83d\udc69\u200d\ud83d\udd2c", + "\ud83e\udd37\u200d\u2640\ufe0f", + "\ud83d\udc69\u200d\ud83c\udfa4", + "\ud83d\udc69\u200d\ud83c\udf93", + "\ud83d\udc69\u200d\ud83c\udfeb", + "\ud83d\udc69\u200d\ud83d\udcbb", + "\ud83e\uddd5", + "\ud83d\udc69\u200d\ud83e\uddaf", + "\ud83d\udc73\u200d\u2640\ufe0f", + "\ud83d\udc5a", + "\ud83d\udc52", + "\ud83e\udd3c\u200d\u2640\ufe0f", + "\ud83d\udeba", + "\ud83e\udeb5", + "\ud83e\udd74", + "\ud83d\uddfa\ufe0f", + "\ud83e\udeb1", + "\ud83d\ude1f", + "\ud83d\udd27", + "\ud83e\udd3c", + "\u270d\ufe0f", + "\u274c", + "\ud83e\ude7b", + "\ud83e\uddf6", + "\ud83e\udd71", + "\ud83d\udfe1", + "\ud83d\udc9b", + "\ud83d\udfe8", + "\ud83c\uddfe\ud83c\uddea", + "\ud83d\udcb4", + "\u262f\ufe0f", + "\ud83e\ude80", + "\ud83d\ude0b", + "\ud83c\uddff\ud83c\uddf2", + "\ud83e\udd2a", + "\u26a1", + "\ud83e\udd93", + "0\ufe0f\u20e3", + "\ud83c\uddff\ud83c\uddfc", + "\ud83e\udd10", + "\ud83e\udddf", + "\ud83e\udddf\u200d\u2642\ufe0f", + "\ud83e\udddf\u200d\u2640\ufe0f", + "\ud83d\udca4" + ] + } + }, + "required": [ + "emoji" + ], + "title": "CreateApiMessageReactionRequest" + }, + "CreateApiOrgMemberRequest": { + "type": "object", + "properties": { + "members": { + "type": "array", + "items": { + "type": "string" + }, + "minItems": 1, + "maxItems": 255, + "uniqueItems": true + }, + "share_history": { + "type": "boolean" + } + }, + "required": [ + "members", + "share_history" + ], + "title": "CreateApiOrgMemberRequest" + }, + "CreateApiOrgRequest": { + "type": "object", + "properties": { + "name": { + "type": [ + "string", + "null" + ], + "maxLength": 60 + }, + "members": { + "type": "array", + "items": { + "type": "string" + }, + "minItems": 1, + "maxItems": 255, + "uniqueItems": true + } + }, + "required": [ + "members" + ], + "title": "CreateApiOrgRequest" + }, + "CreateApiScheduledCommitRequest": { + "type": "object", + "description": "A commit queued from the app, sent as JSON, or with images as multipart, checked as the web checks one. It can't\nreply to or quote a commit, as on the web.", + "properties": { + "body": { + "type": "string", + "description": "At most 4,000 characters, where a link outside code counts as 23 at most. Each link must be 2,048 characters at most.", + "minLength": 1, + "maxLength": 40000 + }, + "author": { + "type": [ + "string", + "null" + ] + }, + "scheduled_at": { + "type": "string" + }, + "parent_id": { + "type": "string" + }, + "quoted_commit_id": { + "type": "string" + }, + "link_preview_url": { + "type": [ + "string", + "null" + ], + "enum": [ + "", + null + ] + }, + "poll": { + "type": [ + "object", + "null" + ], + "properties": { + "options": { + "type": "array", + "items": { + "type": "string", + "maxLength": 50 + }, + "uniqueItems": true + }, + "duration": { + "$ref": "#/components/schemas/PollDuration" + } + }, + "required": [ + "options", + "duration" + ] + }, + "image_descriptions": { + "type": [ + "array", + "null" + ], + "items": { + "type": [ + "string", + "null" + ], + "maxLength": 1000 + } + } + }, + "required": [ + "body", + "scheduled_at" + ], + "title": "CreateApiScheduledCommitRequest" + }, + "CurrentUserResource": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "handle": { + "type": "string" + }, + "name": { + "type": "string" + }, + "avatar_url": { + "type": [ + "string", + "null" + ] + }, + "bio": { + "type": [ + "string", + "null" + ] + }, + "company": { + "type": [ + "string", + "null" + ] + }, + "location": { + "type": [ + "string", + "null" + ] + }, + "website": { + "type": [ + "string", + "null" + ] + }, + "github_url": { + "type": "string" + }, + "html_url": { + "type": "string" + }, + "feed_url": { + "type": "string" + }, + "created_at": { + "type": "string" + }, + "live": { + "type": [ + "object", + "null" + ], + "properties": { + "platform": { + "type": "string" + }, + "url": { + "type": "string" + }, + "thumbnail_url": { + "type": "string" + }, + "ends_at": { + "type": "string" + } + }, + "required": [ + "platform", + "url", + "thumbnail_url", + "ends_at" + ] + }, + "commits_count": { + "type": "integer" + }, + "followers_count": { + "type": "integer" + }, + "following_count": { + "type": "integer" + }, + "lane": { + "type": [ + "string", + "integer" + ] + }, + "is_followed": { + "type": "string" + }, + "follows_you": { + "type": "string" + }, + "followed_by_following_count": { + "type": "string" + }, + "pasteis_mode": { + "type": "boolean" + }, + "pasteis_remaining": { + "type": "integer" + }, + "pasteis_resets_at": { + "type": "string" + }, + "pasteis_received": { + "type": "integer" + }, + "preferred_lane": { + "type": [ + "null", + "string", + "integer", + "object" + ] + }, + "automatic_lane": { + "type": "integer" + }, + "sponsors_url": { + "type": [ + "string", + "null" + ] + }, + "github_synced_at": { + "type": [ + "string", + "null" + ] + }, + "terms_version": { + "type": "string" + }, + "terms_accepted_at": { + "type": [ + "string", + "null" + ] + }, + "terms_accepted": { + "type": "boolean" + }, + "remotes": { + "type": [ + "object", + "null" + ], + "properties": { + "from": { + "$ref": "#/components/schemas/RemotesFrom" + }, + "pull_receipts": { + "type": "boolean" + }, + "requests": { + "type": "boolean" + }, + "everyone": { + "type": "boolean" + }, + "unread_count": { + "type": "integer" + } + }, + "required": [ + "from", + "pull_receipts", + "requests", + "everyone", + "unread_count" + ] + }, + "organizations": { + "type": "array", + "items": { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "organization" + }, + "id": { + "type": "string" + }, + "role": {}, + "handle": { + "type": "string" + }, + "name": { + "type": "string" + }, + "avatar_url": { + "type": [ + "string", + "null" + ] + }, + "bio": { + "type": [ + "string", + "null" + ] + }, + "location": { + "type": [ + "string", + "null" + ] + }, + "website": { + "type": [ + "string", + "null" + ] + }, + "github_url": { + "type": "string" + }, + "html_url": { + "type": "string" + }, + "lane": { + "type": [ + "null", + "string", + "integer", + "object" + ] + }, + "is_followed": { + "type": "string" + }, + "followers_count": { + "type": "integer" + }, + "admins": { + "type": "array", + "items": { + "$ref": "#/components/schemas/UserResource" + } + } + }, + "required": [ + "type", + "id", + "role", + "handle", + "name", + "avatar_url", + "bio", + "location", + "website", + "github_url", + "html_url", + "lane" + ] + } + } + }, + "required": [ + "id", + "handle", + "name", + "avatar_url", + "bio", + "company", + "location", + "website", + "github_url", + "html_url", + "feed_url", + "created_at", + "live", + "pasteis_mode", + "pasteis_remaining", + "pasteis_resets_at", + "pasteis_received", + "preferred_lane", + "automatic_lane", + "sponsors_url", + "github_synced_at", + "terms_version", + "terms_accepted_at", + "terms_accepted", + "remotes", + "organizations" + ], + "title": "CurrentUserResource" + }, + "DeviceResource": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "name": { + "type": "string" + }, + "app_name": { + "type": [ + "string", + "null" + ] + }, + "fingerprint": { + "type": "string" + }, + "approved_at": { + "type": "string" + }, + "last_used_at": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "id", + "name", + "app_name", + "fingerprint", + "approved_at", + "last_used_at" + ], + "title": "DeviceResource" + }, + "LinkPreview": { + "type": "object", + "properties": { + "url": { + "type": "string" + }, + "title": { + "type": [ + "string", + "null" + ] + }, + "description": { + "type": [ + "string", + "null" + ] + }, + "image_url": { + "type": [ + "string", + "null" + ] + }, + "site_name": { + "type": [ + "string", + "null" + ] + }, + "is_pending": { + "type": "boolean" + }, + "embed": { + "type": [ + "object", + "null" + ], + "properties": { + "provider": { + "type": "string" + }, + "kind": { + "type": "string", + "enum": [ + "video", + "audio", + "code" + ] + }, + "src": { + "type": "string" + }, + "aspect_ratio": { + "type": [ + "string", + "null" + ] + }, + "height": { + "type": [ + "integer", + "null" + ] + }, + "poster": { + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "provider", + "kind", + "src", + "aspect_ratio", + "height", + "poster" + ] + } + }, + "required": [ + "url", + "title", + "description", + "image_url", + "site_name", + "is_pending", + "embed" + ], + "title": "LinkPreview" + }, + "Log": { + "type": "string", + "enum": [ + "following", + "latest", + "trending" + ], + "title": "Log" + }, + "MessageReaction": { + "type": "object", + "properties": { + "user_id": { + "type": "string" + }, + "emoji": { + "type": "string" + } + }, + "required": [ + "user_id", + "emoji" + ], + "title": "MessageReaction" + }, + "MessageResource": { + "type": "object", + "properties": { + "id": { + "type": "integer" + }, + "user_id": { + "type": "string" + }, + "client_id": { + "type": "string" + }, + "body": { + "type": "string" + }, + "body_segments": { + "anyOf": [ + { + "type": "array", + "prefixItems": [ + { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "text" + }, + "text": { + "type": "string" + } + }, + "required": [ + "type", + "text" + ] + } + ], + "minItems": 1, + "maxItems": 1 + }, + { + "type": "array", + "items": { + "anyOf": [ + { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "block" + }, + "language": { + "type": [ + "string", + "null" + ] + }, + "filename": { + "type": [ + "string", + "null" + ] + }, + "html": { + "type": "string" + } + }, + "required": [ + "type", + "language", + "filename", + "html" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "code" + }, + "code": { + "type": "string" + } + }, + "required": [ + "type", + "code" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "text" + }, + "text": { + "type": "string" + } + }, + "required": [ + "type", + "text" + ] + } + ] + } + } + ] + }, + "mentions": { + "type": "array", + "items": { + "type": "object", + "properties": { + "handle": { + "type": "string" + }, + "offset": { + "type": "integer" + }, + "length": { + "type": "integer" + }, + "kind": { + "type": "string", + "enum": [ + "organization", + "user" + ] + } + }, + "required": [ + "handle", + "offset", + "length", + "kind" + ] + } + }, + "reply_to_id": { + "type": [ + "integer", + "null" + ] + }, + "reply_to": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "user_id": { + "type": "string" + }, + "body": { + "type": "string" + }, + "images_count": { + "type": "integer", + "minimum": 0 + }, + "has_voice": { + "type": "string" + } + }, + "required": [ + "id", + "user_id", + "body", + "images_count", + "has_voice" + ] + }, + "link_preview": { + "anyOf": [ + { + "$ref": "#/components/schemas/LinkPreview" + }, + { + "type": "null" + } + ] + }, + "images": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "width": { + "type": "integer" + }, + "height": { + "type": "integer" + }, + "description": { + "type": [ + "string", + "null" + ] + }, + "url": { + "type": "string" + } + }, + "required": [ + "id", + "width", + "height", + "description", + "url" + ] + } + }, + "voice": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "duration_ms": { + "type": "string" + }, + "waveform": { + "type": "string" + }, + "url": { + "type": "string" + } + }, + "required": [ + "id", + "duration_ms", + "waveform", + "url" + ] + }, + "reactions": { + "type": "array", + "items": { + "$ref": "#/components/schemas/MessageReaction" + } + }, + "event": { + "anyOf": [ + { + "$ref": "#/components/schemas/OrgEvent" + }, + { + "type": "null" + } + ] + }, + "subject_id": { + "type": [ + "string", + "null" + ] + }, + "user": { + "$ref": "#/components/schemas/UserResource" + }, + "subject": { + "$ref": "#/components/schemas/UserResource" + }, + "pinned_at": { + "type": [ + "string", + "null" + ] + }, + "created_at": { + "type": "string" + } + }, + "required": [ + "id", + "user_id", + "client_id", + "body", + "body_segments", + "mentions", + "event", + "subject_id", + "pinned_at", + "created_at" + ], + "title": "MessageResource" + }, + "NotificationResource": { + "type": "object", + "properties": { + "id": { + "anyOf": [ + { + "type": "string" + }, + {} + ] + }, + "type": { + "anyOf": [ + { + "$ref": "#/components/schemas/NotificationType" + }, + {} + ] + }, + "subject_id": { + "anyOf": [ + { + "type": [ + "string", + "null" + ] + }, + {} + ] + }, + "reason": { + "anyOf": [ + { + "type": [ + "string", + "null" + ] + }, + {} + ] + }, + "read_at": { + "anyOf": [ + { + "type": [ + "string", + "null" + ] + }, + {} + ] + }, + "created_at": { + "anyOf": [ + { + "type": "string" + }, + {} + ] + }, + "actor": { + "anyOf": [ + { + "$ref": "#/components/schemas/ProfileResource" + }, + {} + ] + }, + "actors": { + "anyOf": [ + { + "type": "array", + "items": { + "$ref": "#/components/schemas/ProfileResource" + } + }, + {} + ] + }, + "organization": { + "anyOf": [ + { + "anyOf": [ + { + "$ref": "#/components/schemas/OrganizationResource" + }, + { + "type": "null" + } + ] + }, + {} + ] + }, + "group_id": { + "anyOf": [ + { + "type": "string" + }, + {} + ] + }, + "event_count": { + "anyOf": [ + { + "type": "integer" + }, + {} + ] + }, + "actors_count": { + "anyOf": [ + { + "type": "integer" + }, + {} + ] + }, + "unread_count": { + "anyOf": [ + { + "type": "integer" + }, + {} + ] + }, + "commit": { + "anyOf": [ + { + "anyOf": [ + { + "$ref": "#/components/schemas/CommitResource" + }, + { + "type": "null" + } + ] + }, + {} + ] + } + }, + "required": [ + "id", + "type", + "subject_id", + "reason", + "read_at", + "created_at", + "actor", + "organization", + "group_id", + "event_count", + "actors_count", + "unread_count", + "commit" + ], + "additionalProperties": {}, + "title": "NotificationResource" + }, + "NotificationType": { + "type": "string", + "enum": [ + "followed", + "replied", + "mentioned", + "approved", + "rejected", + "quoted", + "starred", + "leveled_up", + "first_commit", + "timed_out" + ], + "title": "NotificationType" + }, + "OrgEvent": { + "type": "string", + "description": "What a remote records in its history, shown as log lines between messages: membership changes, pings and calls.\n", + "enum": [ + "created", + "added", + "removed", + "left", + "renamed", + "promoted", + "demoted", + "inherited", + "ping", + "call_started", + "call_answered", + "call_cancelled", + "call_declined", + "call_missed", + "call_failed" + ], + "title": "OrgEvent" + }, + "OrgRole": { + "type": "string", + "description": "Maintainers run the org: they rename it, add and remove people, and promote others. Contributors push and read.\n", + "enum": [ + "maintainer", + "contributor" + ], + "title": "OrgRole" + }, + "OrgThreadResource": { + "type": "object", + "properties": { + "org": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "name": { + "type": "string" + } + }, + "required": [ + "id", + "name" + ] + }, + "messages": { + "type": "array", + "items": { + "$ref": "#/components/schemas/MessageResource" + } + }, + "pinned": { + "type": [ + "array", + "null" + ], + "items": { + "$ref": "#/components/schemas/MessageResource" + } + }, + "mentions": { + "type": "array", + "items": { + "$ref": "#/components/schemas/MessageResource" + } + }, + "members": { + "type": "string" + } + }, + "required": [ + "org", + "messages", + "pinned", + "mentions", + "members" + ], + "additionalProperties": {}, + "title": "OrgThreadResource" + }, + "OrganizationResource": { + "type": "object", + "properties": { + "handle": { + "type": "string" + }, + "name": { + "type": "string" + }, + "avatar_url": { + "type": [ + "string", + "null" + ] + }, + "bio": { + "type": [ + "string", + "null" + ] + }, + "location": { + "type": [ + "string", + "null" + ] + }, + "website": { + "type": [ + "string", + "null" + ] + }, + "github_url": { + "type": "string" + }, + "html_url": { + "type": "string" + }, + "lane": { + "type": [ + "null", + "string", + "integer", + "object" + ] + }, + "is_followed": { + "type": "string" + }, + "followers_count": { + "type": "integer" + }, + "admins": { + "type": "array", + "items": { + "$ref": "#/components/schemas/UserResource" + } + } + }, + "required": [ + "handle", + "name", + "avatar_url", + "bio", + "location", + "website", + "github_url", + "html_url", + "lane" + ], + "title": "OrganizationResource" + }, + "PollDuration": { + "type": "integer", + "enum": [ + 60, + 1440, + 4320, + 10080 + ], + "title": "PollDuration" + }, + "PollResource": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "closes_at": { + "type": [ + "string", + "null" + ] + }, + "is_closed": { + "type": "boolean" + }, + "has_voted": { + "type": "boolean" + }, + "total_votes": { + "type": [ + "number", + "null" + ] + }, + "options": { + "type": "array", + "items": {} + } + }, + "required": [ + "id", + "closes_at", + "is_closed", + "has_voted", + "total_votes", + "options" + ], + "title": "PollResource" + }, + "ProfileResource": { + "anyOf": [ + { + "type": "object", + "properties": { + "type": { + "$ref": "#/components/schemas/ProfileType" + }, + "id": { + "type": "string" + }, + "handle": { + "type": "string" + }, + "name": { + "type": "string" + }, + "avatar_url": { + "type": [ + "string", + "null" + ] + }, + "bio": { + "type": [ + "string", + "null" + ] + }, + "location": { + "type": [ + "string", + "null" + ] + }, + "website": { + "type": [ + "string", + "null" + ] + }, + "github_url": { + "type": "string" + }, + "html_url": { + "type": "string" + }, + "lane": { + "type": [ + "null", + "string", + "integer", + "object" + ] + }, + "is_followed": { + "type": [ + "string", + "object" + ] + }, + "followers_count": { + "type": [ + "integer", + "object" + ] + }, + "admins": { + "type": "array", + "items": { + "$ref": "#/components/schemas/UserResource" + } + } + }, + "required": [ + "type", + "id", + "handle", + "name", + "avatar_url", + "bio", + "location", + "website", + "github_url", + "html_url", + "lane", + "is_followed", + "followers_count", + "admins" + ] + }, + { + "type": "object", + "properties": { + "type": { + "$ref": "#/components/schemas/ProfileType" + }, + "id": { + "type": "string" + }, + "handle": { + "type": "string" + }, + "name": { + "type": "string" + }, + "avatar_url": { + "type": [ + "string", + "null" + ] + }, + "bio": { + "type": [ + "string", + "null" + ] + }, + "company": { + "type": [ + "string", + "null" + ] + }, + "location": { + "type": [ + "string", + "null" + ] + }, + "website": { + "type": [ + "string", + "null" + ] + }, + "github_url": { + "type": "string" + }, + "html_url": { + "type": "string" + }, + "feed_url": { + "type": "string" + }, + "created_at": { + "type": "string" + }, + "live": { + "type": [ + "object", + "null" + ], + "properties": { + "platform": { + "type": "string" + }, + "url": { + "type": "string" + }, + "thumbnail_url": { + "type": "string" + }, + "ends_at": { + "type": "string" + } + }, + "required": [ + "platform", + "url", + "thumbnail_url", + "ends_at" + ] + }, + "commits_count": { + "type": [ + "integer", + "object" + ] + }, + "followers_count": { + "type": [ + "integer", + "object" + ] + }, + "following_count": { + "type": [ + "integer", + "object" + ] + }, + "lane": { + "type": [ + "string", + "integer", + "object" + ] + }, + "is_followed": { + "type": [ + "string", + "object" + ] + }, + "follows_you": { + "type": [ + "string", + "object" + ] + }, + "followed_by_following_count": { + "type": [ + "string", + "object" + ] + } + }, + "required": [ + "type", + "id", + "handle", + "name", + "avatar_url", + "bio", + "company", + "location", + "website", + "github_url", + "html_url", + "feed_url", + "created_at", + "live", + "commits_count", + "followers_count", + "following_count", + "lane", + "is_followed", + "follows_you", + "followed_by_following_count" + ] + } + ], + "title": "ProfileResource" + }, + "ProfileType": { + "type": "string", + "description": "The kind of GitHub account a profile mirrors, as GitHub's `ProfileOwner` is a user or an organization.\n", + "enum": [ + "user", + "organization" + ], + "title": "ProfileType" + }, + "PushPlatform": { + "type": "string", + "description": "What kind of phone a push token is for, which decides how a push to it is shaped.\n", + "enum": [ + "ios", + "android" + ], + "title": "PushPlatform" + }, + "RateLimitError": { + "type": "object", + "properties": { + "message": { + "type": "string", + "description": "How long to wait, or which limit was reached." + }, + "code": { + "type": "string", + "description": "Only a signed request gets it, and never from the pings and commit search limits.", + "enum": [ + "rate_limited" + ] + } + }, + "required": [ + "message" + ], + "title": "RateLimitError" + }, + "RemoteCandidateResource": { + "type": "object", + "properties": { + "user": { + "$ref": "#/components/schemas/UserResource" + }, + "reason": { + "type": "string" + } + }, + "required": [ + "user", + "reason" + ], + "title": "RemoteCandidateResource" + }, + "RemotesFrom": { + "type": "string", + "description": "Who can start a conversation straight away. Anyone else lands in the recipient's fetched requests.\n", + "enum": [ + "following", + "everyone" + ], + "title": "RemotesFrom" + }, + "ScheduledCommitResource": { + "type": "object", + "properties": { + "id": { + "anyOf": [ + { + "type": "string" + }, + {} + ] + }, + "author": { + "anyOf": [ + { + "type": [ + "array", + "null" + ], + "items": {} + }, + {} + ] + }, + "poll_options": { + "anyOf": [ + { + "type": "array", + "items": { + "type": "string" + } + }, + { + "type": "string" + }, + { + "type": "null" + } + ] + }, + "image_count": { + "type": "integer" + }, + "scheduled_at": { + "type": "string" + }, + "submitted_at": { + "type": [ + "string", + "null" + ] + }, + "status": { + "type": "string", + "enum": [ + "scheduled", + "deleted", + "pending", + "approved", + "rejected" + ] + } + }, + "required": [ + "id", + "author", + "poll_options", + "image_count", + "scheduled_at", + "submitted_at", + "status" + ], + "additionalProperties": {}, + "title": "ScheduledCommitResource" + }, + "UpdateApiConversationCallRequest": { + "type": "object", + "properties": { + "sdp": { + "type": "string", + "maxLength": 10000 + } + }, + "required": [ + "sdp" + ], + "title": "UpdateApiConversationCallRequest" + }, + "UpdateApiConversationMuteRequest": { + "type": "object", + "properties": { + "duration": { + "$ref": "#/components/schemas/ConversationMuteDuration" + } + }, + "required": [ + "duration" + ], + "title": "UpdateApiConversationMuteRequest" + }, + "UpdateApiConversationPinRequest": { + "type": "object", + "properties": { + "pinned": { + "type": "boolean" + } + }, + "required": [ + "pinned" + ], + "title": "UpdateApiConversationPinRequest" + }, + "UpdateApiConversationReadRequest": { + "type": "object", + "properties": { + "through": { + "type": "integer", + "minimum": 0 + } + }, + "required": [ + "through" + ], + "title": "UpdateApiConversationReadRequest" + }, + "UpdateApiDevicePushTokenRequest": { + "type": "object", + "properties": { + "token": { + "type": "string", + "maxLength": 4096 + }, + "platform": { + "$ref": "#/components/schemas/PushPlatform" + } + }, + "required": [ + "token", + "platform" + ], + "title": "UpdateApiDevicePushTokenRequest" + }, + "UpdateApiOrgCallRequest": { + "type": "object", + "properties": { + "signals": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "maxLength": 64 + }, + "type": { + "type": "string", + "enum": [ + "offer", + "answer" + ] + }, + "sdp": { + "type": "string", + "maxLength": 10000 + } + }, + "required": [ + "id", + "type", + "sdp" + ] + }, + "maxItems": 8 + } + }, + "required": [ + "signals" + ], + "title": "UpdateApiOrgCallRequest" + }, + "UpdateApiOrgMemberRequest": { + "type": "object", + "properties": { + "role": { + "$ref": "#/components/schemas/OrgRole" + } + }, + "required": [ + "role" + ], + "title": "UpdateApiOrgMemberRequest" + }, + "UpdateApiOrgMuteRequest": { + "type": "object", + "properties": { + "duration": { + "$ref": "#/components/schemas/ConversationMuteDuration" + } + }, + "required": [ + "duration" + ], + "title": "UpdateApiOrgMuteRequest" + }, + "UpdateApiOrgPinRequest": { + "type": "object", + "properties": { + "pinned": { + "type": "boolean" + } + }, + "required": [ + "pinned" + ], + "title": "UpdateApiOrgPinRequest" + }, + "UpdateApiOrgReadRequest": { + "type": "object", + "properties": { + "through": { + "type": "integer", + "minimum": 0 + } + }, + "required": [ + "through" + ], + "title": "UpdateApiOrgReadRequest" + }, + "UpdateApiOrgRequest": { + "type": "object", + "properties": { + "name": { + "type": [ + "string", + "null" + ], + "maxLength": 60 + } + }, + "title": "UpdateApiOrgRequest" + }, + "UpdateApiUserAutomaticTranslationRequest": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean" + } + }, + "required": [ + "enabled" + ], + "title": "UpdateApiUserAutomaticTranslationRequest" + }, + "UpdateApiUserLaneRequest": { + "type": "object", + "properties": { + "lane": { + "type": [ + "integer", + "null" + ], + "minimum": 0, + "maximum": 5 + }, + "color": { + "type": [ + "string", + "null" + ], + "pattern": "^#[0-9a-f]{6}$" + } + }, + "required": [ + "lane" + ], + "title": "UpdateApiUserLaneRequest" + }, + "UpdateApiUserLiveRequest": { + "type": "object", + "properties": { + "url": { + "type": "string", + "maxLength": 2048 + }, + "hours": { + "type": "integer", + "minimum": 1, + "maximum": 12 + } + }, + "required": [ + "url", + "hours" + ], + "title": "UpdateApiUserLiveRequest" + }, + "UpdateApiUserPasteisModeRequest": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean" + } + }, + "required": [ + "enabled" + ], + "title": "UpdateApiUserPasteisModeRequest" + }, + "UpdateApiUserPushPreferencesRequest": { + "type": "object", + "properties": { + "follows": { + "type": "boolean" + }, + "replies": { + "type": "boolean" + }, + "mentions": { + "type": "boolean" + }, + "direct_remotes": { + "type": "boolean" + }, + "org_remotes": { + "type": "boolean" + } + }, + "required": [ + "follows", + "replies", + "mentions", + "direct_remotes", + "org_remotes" + ], + "title": "UpdateApiUserPushPreferencesRequest" + }, + "UpdateApiUserRemotePreferencesRequest": { + "type": "object", + "properties": { + "from": { + "type": "string", + "description": "Who can start a conversation straight away. Anyone else lands in the recipient's fetched requests.\n", + "const": "following" + }, + "pull_receipts": { + "type": "boolean" + } + }, + "required": [ + "from", + "pull_receipts" + ], + "title": "UpdateApiUserRemotePreferencesRequest" + }, + "UpdateApiUserRemotesRequest": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean" + } + }, + "required": [ + "enabled" + ], + "title": "UpdateApiUserRemotesRequest" + }, + "UpdateApiUserTermsRequest": { + "type": "object", + "description": "The app says which version of the terms the person was shown, so an old build can't accept a version it never\nshowed them.", + "properties": { + "version": { + "type": "string", + "enum": [ + "2026-11-01T14:35:00Z" + ] + } + }, + "required": [ + "version" + ], + "title": "UpdateApiUserTermsRequest" + }, + "UpdateApiUserTimezoneRequest": { + "type": "object", + "properties": { + "timezone": { + "type": [ + "string", + "null" + ] + }, + "show_local_time": { + "type": [ + "boolean", + "null" + ] + } + }, + "required": [ + "timezone" + ], + "title": "UpdateApiUserTimezoneRequest" + }, + "UpdateApiUserTranslationLanguageRequest": { + "type": "object", + "properties": { + "translation_language": { + "type": [ + "string", + "null" + ], + "enum": [ + "af", + "agq", + "ak", + "am", + "ar", + "as", + "asa", + "ast", + "az", + "ba", + "bas", + "be", + "bem", + "bez", + "bg", + "bgc", + "bho", + "blo", + "bm", + "bn", + "bo", + "br", + "brx", + "bs", + "bua", + "ca", + "ccp", + "ce", + "ceb", + "cgg", + "chr", + "ckb", + "cs", + "csw", + "cv", + "cy", + "da", + "dav", + "de", + "dje", + "doi", + "dsb", + "dua", + "dyo", + "dz", + "ebu", + "ee", + "el", + "en", + "eo", + "es", + "et", + "eu", + "ewo", + "fa", + "ff", + "fi", + "fil", + "fo", + "fr", + "fur", + "fy", + "ga", + "gaa", + "gd", + "gl", + "gsw", + "gu", + "guz", + "gv", + "ha", + "haw", + "he", + "hi", + "hr", + "hsb", + "hu", + "hy", + "ia", + "id", + "ie", + "ig", + "ii", + "is", + "it", + "ja", + "jgo", + "jmc", + "jv", + "ka", + "kab", + "kam", + "kde", + "kea", + "kgp", + "khq", + "ki", + "kk", + "kkj", + "kl", + "kln", + "km", + "kn", + "ko", + "kok", + "ks", + "ksb", + "ksf", + "ksh", + "ku", + "kw", + "kxv", + "ky", + "lag", + "lb", + "lg", + "lij", + "lkt", + "lmo", + "ln", + "lo", + "lrc", + "lt", + "lu", + "luo", + "luy", + "lv", + "mai", + "mas", + "mer", + "mfe", + "mg", + "mgh", + "mgo", + "mi", + "mk", + "ml", + "mn", + "mni", + "mr", + "ms", + "mt", + "mua", + "my", + "mzn", + "naq", + "nb", + "nd", + "nds", + "ne", + "nl", + "nmg", + "nn", + "nnh", + "no", + "nqo", + "nso", + "nus", + "nyn", + "oc", + "om", + "or", + "os", + "pa", + "pcm", + "pl", + "pms", + "prg", + "ps", + "pt", + "qu", + "raj", + "rm", + "rn", + "ro", + "rof", + "ru", + "rw", + "rwk", + "sa", + "sah", + "saq", + "sat", + "sbp", + "sc", + "scn", + "sd", + "se", + "seh", + "ses", + "sg", + "shi", + "shn", + "si", + "sk", + "sl", + "smn", + "sn", + "so", + "sq", + "sr", + "st", + "su", + "sv", + "sw", + "syr", + "szl", + "ta", + "te", + "teo", + "tg", + "th", + "ti", + "tk", + "tn", + "to", + "tok", + "tr", + "tt", + "twq", + "tyv", + "tzm", + "ug", + "uk", + "ur", + "uz", + "vai", + "vec", + "vi", + "vmw", + "vun", + "wae", + "wo", + "xh", + "xnr", + "xog", + "yav", + "yi", + "yo", + "yrl", + "yue", + "za", + "zgh", + "zh", + "zu", + null + ] + } + }, + "required": [ + "translation_language" + ], + "title": "UpdateApiUserTranslationLanguageRequest" + }, + "UserResource": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "handle": { + "type": "string" + }, + "name": { + "type": "string" + }, + "avatar_url": { + "type": [ + "string", + "null" + ] + }, + "bio": { + "type": [ + "string", + "null" + ] + }, + "company": { + "type": [ + "string", + "null" + ] + }, + "location": { + "type": [ + "string", + "null" + ] + }, + "website": { + "type": [ + "string", + "null" + ] + }, + "github_url": { + "type": "string" + }, + "html_url": { + "type": "string" + }, + "feed_url": { + "type": "string" + }, + "created_at": { + "type": "string" + }, + "live": { + "type": [ + "object", + "null" + ], + "properties": { + "platform": { + "type": "string" + }, + "url": { + "type": "string" + }, + "thumbnail_url": { + "type": "string" + }, + "ends_at": { + "type": "string" + } + }, + "required": [ + "platform", + "url", + "thumbnail_url", + "ends_at" + ] + }, + "commits_count": { + "type": "integer" + }, + "followers_count": { + "type": "integer" + }, + "following_count": { + "type": "integer" + }, + "lane": { + "type": [ + "string", + "integer" + ] + }, + "is_followed": { + "type": "string" + }, + "follows_you": { + "type": "string" + }, + "followed_by_following_count": { + "type": "string" + } + }, + "required": [ + "id", + "handle", + "name", + "avatar_url", + "bio", + "company", + "location", + "website", + "github_url", + "html_url", + "feed_url", + "created_at", + "live" + ], + "title": "UserResource" + } + }, + "responses": { + "ValidationException": { + "description": "Validation error", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "message": { + "type": "string", + "description": "Errors overview." + }, + "errors": { + "type": "object", + "description": "A detailed description of each field that failed validation.", + "additionalProperties": { + "type": "array", + "items": { + "type": "string" + } + } + } + }, + "required": [ + "message", + "errors" + ] + } + } + } + }, + "ModelNotFoundException": { + "description": "Not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "message": { + "type": "string", + "description": "Error overview." + } + }, + "required": [ + "message" + ] + } + } + } + }, + "AuthorizationException": { + "description": "Authorization error", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "message": { + "type": "string", + "description": "Error overview." + } + }, + "required": [ + "message" + ] + } + } + } + } + } + } +} \ No newline at end of file diff --git a/resources/js/components/api-docs/choice.ts b/resources/js/components/api-docs/choice.ts new file mode 100644 index 0000000000..333b2bfbad --- /dev/null +++ b/resources/js/components/api-docs/choice.ts @@ -0,0 +1,61 @@ +import { useSyncExternalStore } from 'react'; + +/** + * A choice the reader makes once for the whole of the docs, like a client or a view: kept in the browser, and in step + * across every place that shows it and every tab of the docs. + */ +export function createChoice(key: string) { + const listeners = new Set<() => void>(); + let chosen: string | null | undefined; + + const stored = (): string | null => { + try { + return window.localStorage.getItem(key); + } catch { + return null; + } + }; + + const current = (): string | null => { + if (chosen === undefined) { + chosen = stored(); + } + + return chosen; + }; + + const choose = (value: string): void => { + chosen = value; + + try { + window.localStorage.setItem(key, value); + } catch { + // A private window may refuse it: the choice then lasts as long as the page. + } + + listeners.forEach((listener) => listener()); + }; + + const subscribe = (listener: () => void): (() => void) => { + const onStorage = (event: StorageEvent) => { + // A null key means another tab cleared the whole storage. + if (event.key === key || event.key === null) { + chosen = event.key === null ? null : event.newValue; + listener(); + } + }; + + listeners.add(listener); + window.addEventListener('storage', onStorage); + + return () => { + listeners.delete(listener); + window.removeEventListener('storage', onStorage); + }; + }; + + const useChosen = (): string | null => + useSyncExternalStore(subscribe, current, () => null); + + return { choose, useChosen }; +} diff --git a/resources/js/components/api-docs/endpoint-search.tsx b/resources/js/components/api-docs/endpoint-search.tsx new file mode 100644 index 0000000000..2f9d4f25d2 --- /dev/null +++ b/resources/js/components/api-docs/endpoint-search.tsx @@ -0,0 +1,419 @@ +import { router } from '@inertiajs/react'; +import * as DialogPrimitive from '@radix-ui/react-dialog'; +import { BookOpen, Search } from 'lucide-react'; +import { useEffect, useRef, useState } from 'react'; +import type { KeyboardEvent } from 'react'; +import ApiDocsController from '@/actions/App/Http/Controllers/ApiDocsController'; +import { + EndpointPath, + MethodChip, + endpointAnchor, + revealEndpoint, +} from '@/components/api-docs/endpoint'; +import { searchApiDocs } from '@/components/api-docs/search'; +import type { ApiDocsResult } from '@/components/api-docs/search'; +import { DialogOverlay, DialogPortal } from '@/components/ui/dialog'; +import { isTyping } from '@/hooks/use-keyboard-shortcuts'; +import { hasModKey, useKeyLabels } from '@/lib/keyboard'; +import { cn } from '@/lib/utils'; +import type { ApiDocsIndexEntry, ApiDocsSection } from '@/types'; + +const RESULTS_ID = 'api-docs-search-results'; + +/** + * ⌘K or Ctrl+K from anywhere, or / when the reader is not typing somewhere else. + */ +export function isSearchShortcut(event: { + key: string; + metaKey: boolean; + ctrlKey: boolean; + altKey: boolean; + target: EventTarget | null; +}): boolean { + if (hasModKey(event)) { + return event.key.toLowerCase() === 'k'; + } + + return event.key === '/' && !event.altKey && !isTyping(event.target); +} + +/** + * The result an arrow key moves to, round the ends, or null for any other key. + */ +export function moveActive( + position: number, + key: string, + count: number, +): number | null { + const step = { ArrowDown: 1, ArrowUp: -1 }[key]; + + if (step === undefined || count === 0) { + return null; + } + + return (Math.min(position, count - 1) + step + count) % count; +} + +/** + * What the reader typed and the result they are on, kept while the search closes so its contents stay still through + * the exit, and started afresh each time it opens. + */ +export function useSearchQuery(isOpen: boolean) { + const [query, setQuery] = useState(''); + const [activeIndex, setActiveIndex] = useState(0); + const [wasOpen, setWasOpen] = useState(isOpen); + + if (isOpen !== wasOpen) { + setWasOpen(isOpen); + + if (isOpen) { + setQuery(''); + setActiveIndex(0); + } + } + + const type = (value: string) => { + setQuery(value); + setActiveIndex(0); + }; + + return { query, type, activeIndex, setActiveIndex }; +} + +function resultId(result: ApiDocsResult): string { + return `api-docs-search-${result.kind}-${result.id}`; +} + +/** + * Puts the reader where they picked, as if they had tabbed there: on an endpoint's toggle, or on a guide's first + * section. The page has already scrolled there, so focus does not scroll it again. + */ +export function focusResult(result: ApiDocsResult): void { + const selector = + result.kind === 'endpoint' + ? `#${endpointAnchor(result.endpoint)} > button` + : 'main article h2 a'; + + document + .querySelector(selector) + ?.focus({ preventScroll: true }); +} + +/** + * Where focus goes once the search has closed: to what was picked on this page, nowhere yet for a page still + * arriving, since it takes focus once there, or back to the Search button when nothing was picked. The dialog has no + * trigger of its own, so Radix alone would leave focus on the page's body. + */ +export function handOffFocus( + pick: { result: ApiDocsResult; isHere: boolean } | null, + returnFocus: () => void, +): void { + if (pick === null) { + returnFocus(); + + return; + } + + if (pick.isHere) { + focusResult(pick.result); + } +} + +type Visit = (url: string, options: { onSuccess: () => void }) => void; + +/** + * Goes to a guide, or to an endpoint opened at its anchor, and says whether that stays on the page. An endpoint of + * the page already shown is opened in place, as a link to it would, even when the hash already points at it, and the + * search closes at once. Another page closes it only once it has arrived: a visit that fails or is cancelled leaves + * the search open, as typed, with focus in it. Closing says which it was. + */ +export function goToResult( + result: ApiDocsResult, + current: string, + close: (isHere: boolean) => void, + visit: Visit = (url, options) => router.visit(url, options), + reveal: (anchor: string) => void = revealEndpoint, +): boolean { + const arrive = { + onSuccess: () => { + close(false); + window.requestAnimationFrame(() => focusResult(result)); + }, + }; + + if (result.kind === 'guide') { + visit(ApiDocsController.show(result.section.slug).url, arrive); + + return false; + } + + const anchor = endpointAnchor(result.endpoint); + + if (result.section.slug === current) { + close(true); + reveal(anchor); + + return true; + } + + visit( + `${ApiDocsController.show(result.section.slug).url}#${anchor}`, + arrive, + ); + + return false; +} + +/** + * The field and what it finds: a combobox over a listbox of guides and endpoints, the active one on the Accent. + */ +export function SearchPanel({ + query, + results, + activeIndex, + onType, + onActivate, + onPick, +}: { + query: string; + results: ApiDocsResult[]; + activeIndex: number; + onType: (query: string) => void; + onActivate: (index: number) => void; + onPick: (result: ApiDocsResult) => void; +}) { + const keys = useKeyLabels(); + const activeResult = results[Math.min(activeIndex, results.length - 1)]; + + const onKeyDown = (event: KeyboardEvent) => { + if (event.nativeEvent.isComposing || results.length === 0) { + return; + } + + const next = moveActive(activeIndex, event.key, results.length); + + if (next !== null) { + event.preventDefault(); + onActivate(next); + } + + if (event.key === 'Enter' && activeResult) { + event.preventDefault(); + onPick(activeResult); + } + }; + + return ( + <> +
+ + onType(event.target.value)} + onKeyDown={onKeyDown} + placeholder="Search endpoints and guides" + aria-label="Search the API docs" + role="combobox" + aria-expanded={results.length > 0} + aria-controls={results.length > 0 ? RESULTS_ID : undefined} + aria-activedescendant={ + activeResult ? resultId(activeResult) : undefined + } + aria-autocomplete="list" + autoComplete="off" + spellCheck={false} + className="h-14 min-w-0 flex-1 bg-transparent text-[17px] outline-none placeholder:text-muted-foreground focus-visible:outline-none" + /> + + esc + +
+ + {results.length === 0 ? ( +

+ fatal: nothing matches '{query}' +

+ ) : ( +
    + {results.map((result, position) => { + const isActive = result === activeResult; + + return ( +
  • onActivate(position)} + onClick={() => onPick(result)} + className={cn( + 'flex cursor-pointer items-center gap-3 rounded-lg px-3 py-2.5', + isActive && 'bg-accent', + )} + > + {result.kind === 'guide' ? ( + <> + + + + {result.section.title} + + + {result.section.description} + + + + ) : ( + <> + + + + + {result.endpoint.summary} + + + + {result.section.slug} + + + )} + + ↵ + +
  • + ); + })} +
+ )} + +
+ + ↑↓ to move + + + ↵ to open + + + {keys.combo(keys.mod, 'K')}{' '} + anywhere in the docs + +
+ + ); +} + +/** + * The API docs' search: every guide and endpoint, found by the words of their method, path, title and summary, + * as people search does, from ⌘K or / anywhere in the docs. + */ +export function EndpointSearch({ + open: isOpen, + onOpenChange, + sections, + index, + current, + returnFocus, +}: { + open: boolean; + onOpenChange: (open: boolean) => void; + sections: ApiDocsSection[]; + index: ApiDocsIndexEntry[]; + current: string; + returnFocus: () => void; +}) { + const { query, type, activeIndex, setActiveIndex } = useSearchQuery(isOpen); + const results = searchApiDocs(query, sections, index); + const activeResult = results[Math.min(activeIndex, results.length - 1)]; + const activeId = activeResult ? resultId(activeResult) : undefined; + + useEffect(() => { + if (isOpen && activeId) { + document + .getElementById(activeId) + ?.scrollIntoView({ block: 'nearest' }); + } + }, [isOpen, activeId]); + + const picked = useRef<{ result: ApiDocsResult; isHere: boolean } | null>( + null, + ); + + const isOpenNow = useRef(isOpen); + + useEffect(() => { + isOpenNow.current = isOpen; + }, [isOpen]); + + // A pick is only noted once it closes the search, and only while the search is still open: one whose page never + // arrived, or arrived after the reader closed the search, leaves no pick behind for the next close. + const pick = (result: ApiDocsResult) => { + goToResult(result, current, (isHere) => { + if (isOpenNow.current) { + picked.current = { result, isHere }; + onOpenChange(false); + } + }); + }; + + const onCloseAutoFocus = (event: Event) => { + const target = picked.current; + picked.current = null; + event.preventDefault(); + handOffFocus(target, returnFocus); + }; + + return ( + + + + + + Search the API docs + + + Find a guide, or an endpoint by its method, path or what + it does. + + + + + + + ); +} diff --git a/resources/js/components/api-docs/endpoint.tsx b/resources/js/components/api-docs/endpoint.tsx new file mode 100644 index 0000000000..82d796a6d0 --- /dev/null +++ b/resources/js/components/api-docs/endpoint.tsx @@ -0,0 +1,663 @@ +import { Link } from '@inertiajs/react'; +import { ChevronRight, Lock } from 'lucide-react'; +import { Fragment, useState, useSyncExternalStore } from 'react'; +import type { ReactNode } from 'react'; +import ApiDocsController from '@/actions/App/Http/Controllers/ApiDocsController'; +import ApiDocsSchemaController from '@/actions/App/Http/Controllers/ApiDocsSchemaController'; +import { ExampleTabs } from '@/components/api-docs/example-tabs'; +import { FieldTable, SpecText } from '@/components/api-docs/field-table'; +import { loadSchemas, useSchemas } from '@/components/api-docs/schemas'; +import type { + ApiDocsSchema, + ApiDocsSchemas, + SchemasState, +} from '@/components/api-docs/schemas'; +import { DESTRUCTIVE, SUCCESS, WARNING } from '@/components/api-docs/tones'; +import { CodeBlock } from '@/components/code-block'; +import { useIsLate } from '@/hooks/use-is-late'; +import { cn } from '@/lib/utils'; +import type { ApiDocsEndpoint, ApiDocsField, ApiDocsResponse } from '@/types'; + +/** + * An error every endpoint may answer with, which the Errors guide describes once rather than each endpoint. + */ +export function isSharedError(response: ApiDocsResponse): boolean { + return !response.status.startsWith('2') && response.fields.length === 0; +} + +/** + * A method by what it does: reading in green, writing in ochre, deleting in red. No blue, which only ever means + * "act here". + */ +const METHOD_TONES: Record = { + GET: SUCCESS, + POST: WARNING, + PUT: WARNING, + PATCH: WARNING, + DELETE: DESTRUCTIVE, +}; + +let reveals = 0; +const revealListeners = new Set<() => void>(); + +function subscribeToLinks(onChange: () => void): () => void { + window.addEventListener('hashchange', onChange); + revealListeners.add(onChange); + + return () => { + window.removeEventListener('hashchange', onChange); + revealListeners.delete(onChange); + }; +} + +/** + * Points the page at an endpoint, as a link to it would. When the hash already points at it, the browser neither + * scrolls nor says so, so the endpoint is scrolled to and told to open here. + */ +export function revealEndpoint(anchor: string): void { + if (window.location.hash !== `#${anchor}`) { + window.location.hash = anchor; + + return; + } + + reveals += 1; + revealListeners.forEach((listener) => listener()); + document.getElementById(anchor)?.scrollIntoView(); +} + +/** + * Whether an endpoint is unfolded: as the reader left it, until a link points at it anew and opens it. One a link + * opened stays open when the hash moves on: folding it would pull up whatever the new link scrolled to. + */ +export function useEndpointOpen( + anchor: string, +): [boolean, (open: boolean) => void] { + const link = useSyncExternalStore( + subscribeToLinks, + () => (window.location.hash === `#${anchor}` ? reveals : null), + () => null, + ); + const [toggled, setToggled] = useState(null); + const [lastLink, setLastLink] = useState(link); + + if (link !== lastLink) { + setLastLink(link); + + if (link !== null) { + setToggled(null); + } else if (toggled === null && lastLink !== null) { + setToggled(true); + } + } + + return [toggled ?? link !== null, setToggled]; +} + +export function endpointAnchor(endpoint: { id: string }): string { + return `endpoint-${endpoint.id.replace(/[^A-Za-z0-9_-]+/g, '-')}`; +} + +/** + * A path with its parameters muted, so the fixed part reads first: `/users/{handle}/commits`. + */ +export function EndpointPath({ path }: { path: string }) { + return ( + + {path.split(/(\{[^}]+\})/).map((part, index) => ( + + {part.startsWith('{') ? ( + {part} + ) : ( + part + )} + + ))} + + ); +} + +export function MethodChip({ method }: { method: string }) { + return ( + + {method} + + ); +} + +export function SignatureChip({ + signature, +}: { + signature: ApiDocsEndpoint['signature']; +}) { + return ( + + {signature === 'required' && ( + + )} + {signature === 'required' ? 'signed' : 'public'} + + ); +} + +function Part({ + title, + meta, + actions, + children, +}: { + title: string; + meta?: string; + actions?: ReactNode; + children: ReactNode; +}) { + return ( +
+
+

+ {title} + {meta && {meta}} +

+ {actions &&
{actions}
} +
+ {children} +
+ ); +} + +type View = 'fields' | 'schema'; + +type Views = Record<'body' | 'responses' | 'errors', View>; + +/** + * Every part of an endpoint as fields, which is how each one first reads. + */ +export const FIELDS_EVERYWHERE: Views = { + body: 'fields', + responses: 'fields', + errors: 'fields', +}; + +/** + * The views with one part read another way: each part has its own toggle, picked for it alone. + */ +export function pickView(views: Views, part: keyof Views, view: View): Views { + return { ...views, [part]: view }; +} + +/** + * Whether a part reads as JSON schema, which only then makes the endpoint ask for its schemas. + */ +export function wantsSchemas(views: Views): boolean { + return Object.values(views).includes('schema'); +} + +/** + * Fields or JSON schema, for what one part of an endpoint takes or answers: a bordered segmented pair, the picked one + * on the Blue Wash like the theme switch, its 12px label in the pressed blue, which reads at 4.5:1 on the wash where + * Commit Blue does not. + */ +function ViewToggle({ + view, + onChange, +}: { + view: View; + onChange: (view: View) => void; +}) { + return ( +
+ {(['fields', 'schema'] as const).map((option) => ( + + ))} +
+ ); +} + +/** + * The fields, kept in place until their schema arrives so nothing moves, and a word over them only once it takes a + * while. + */ +function FieldsWhileLoading({ fields }: { fields: ApiDocsField[] }) { + const isLate = useIsLate(true); + + return ( +
+
+ +
+

+ {isLate && ( + + Loading the schema… + + )} +

+
+ ); +} + +/** + * Fields as a table, or the JSON schema they come from, loaded when the reader asks for it. + */ +export function SchemaOrFields({ + fields, + view, + schemas, + pick, + onRetry, +}: { + fields: ApiDocsField[]; + view: 'fields' | 'schema'; + schemas: SchemasState; + pick: (schemas: ApiDocsSchemas) => ApiDocsSchema | null | undefined; + onRetry: (from: Element) => void; +}) { + if (view === 'fields') { + return ; + } + + if (schemas === 'failed') { + return ( +
+
+ +
+

+ + + fatal: no schema + + + +

+
+ ); + } + + if (schemas === undefined || schemas === 'loading') { + return ; + } + + const schema = pick(schemas); + + return schema ? ( +
+ +
+ ) : ( + + ); +} + +function Answers({ + responses, + view, + schemas, + onRetry, +}: { + responses: ApiDocsResponse[]; + view: 'fields' | 'schema'; + schemas: SchemasState; + onRetry: (from: Element) => void; +}) { + return ( +
    + {responses.map((response) => ( +
  • +

    + + {response.status} + + + + + {isSharedError(response) && ( + + see Errors + + )} +

    + {response.fields.length > 0 && ( + loaded.responses[response.status]} + onRetry={onRetry} + /> + )} +
  • + ))} +
+ ); +} + +/** + * Says once, to a screen reader, that an endpoint's schema failed to load: each of its fields tables only shows it. + */ +export function SchemaFailureAlert({ + endpoint, + schemas, +}: { + endpoint: Pick; + schemas: SchemasState; +}) { + if (schemas !== 'failed') { + return null; + } + + return ( +

+ {`The schema of ${endpoint.method} ${endpoint.path.replace(/[{}]/g, '')} could not be loaded.`} +

+ ); +} + +/** + * Asks for a schema again, and hands keyboard focus to what stays on screen: the button pressed goes away with the + * failure, which would send focus back to the top of the page. A schema that loads can be much shorter than the + * fields it replaces, so once it is drawn, the focused toggle is brought back in sight if it left it, unless the + * reader scrolled, or moved focus, meanwhile: what they did then wins. + */ +export async function retryKeepingFocus( + retry: () => Promise, + target: HTMLElement | null, +): Promise { + if (target === null) { + return retry(); + } + + let isReleased = false; + let isLoaded = false; + const release = () => { + isReleased = true; + }; + // Any scroll while the schema loads is the reader's: nothing moves on the page meanwhile. Once it is drawn, the page + // may scroll by itself as it gets shorter, so only the reader's own input still counts until that frame. + const inputs = ['wheel', 'touchmove', 'keydown'] as const; + const stopListening = () => + inputs.forEach((input) => window.removeEventListener(input, release)); + [...inputs, 'scroll' as const].forEach((input) => + window.addEventListener(input, release, { passive: true }), + ); + + try { + const loading = retry(); + target.focus({ preventScroll: true }); + await loading; + isLoaded = true; + } finally { + window.removeEventListener('scroll', release); + + if (!isLoaded) { + stopListening(); + } + } + + if (isReleased || document.activeElement !== target) { + stopListening(); + + return; + } + + requestAnimationFrame(() => { + stopListening(); + + if (!isReleased) { + target.scrollIntoView({ block: 'nearest' }); + } + }); +} + +/** + * The toggle of the part a Try again was pressed in, which stays right where the reader is, unlike another part's. + */ +export function retryTarget(from: Element): HTMLElement | null { + return ( + from + .closest('[data-part]') + ?.querySelector('button[aria-pressed="true"]') ?? null + ); +} + +/** + * Whether an endpoint shows any fields its schemas would replace: one without has nothing to ask them for. + */ +export function hasSchemaTables( + endpoint: Pick, +): boolean { + return ( + (endpoint.body?.fields.length ?? 0) > 0 || + endpoint.responses.some((response) => response.fields.length > 0) + ); +} + +/** + * What an endpoint takes, its path and query parameters apart, and what it answers, its errors apart. Its body, its + * responses and its errors each read as fields or as JSON schema, as the reader picks for that part alone. + */ +export function EndpointDetails({ + endpoint, + section, +}: { + endpoint: ApiDocsEndpoint; + section: string; +}) { + const [views, setViews] = useState(FIELDS_EVERYWHERE); + const toggle = (part: keyof Views) => ( + setViews(pickView(views, part, view))} + /> + ); + const schemasUrl = + wantsSchemas(views) && hasSchemaTables(endpoint) + ? ApiDocsSchemaController.show({ section, endpoint: endpoint.id }) + .url + : null; + const schemas = useSchemas(schemasUrl); + const retry = (from: Element) => { + if (schemasUrl !== null) { + void retryKeepingFocus( + () => loadSchemas(schemasUrl), + retryTarget(from), + ); + } + }; + const path = endpoint.parameters.filter( + (parameter) => parameter.in === 'path', + ); + const query = endpoint.parameters.filter( + (parameter) => parameter.in === 'query', + ); + const successes = endpoint.responses.filter((response) => + response.status.startsWith('2'), + ); + const errors = endpoint.responses.filter( + (response) => !response.status.startsWith('2'), + ); + + return ( +
+ +
+

+ +

+ {endpoint.description && ( +

+ +

+ )} +
+ + {path.length > 0 && ( + + + + )} + + {query.length > 0 && ( + + + + )} + + {endpoint.body && endpoint.body.fields.length > 0 && ( + + loaded.body} + onRetry={retry} + /> + + )} + + {successes.length > 0 && ( + response.fields.length > 0) + ? toggle('responses') + : undefined + } + > + + + )} + + {errors.length > 0 && ( + response.fields.length > 0) + ? toggle('errors') + : undefined + } + > + + + )} +
+ ); +} + +/** + * An endpoint of the reference: folded to its method, path and summary, and unfolded to what it takes and what it + * answers. The one a link points at opens by itself. + */ +export function Endpoint({ + endpoint, + section, +}: { + endpoint: ApiDocsEndpoint; + section: string; +}) { + const anchor = endpointAnchor(endpoint); + const [isOpen, setIsOpen] = useEndpointOpen(anchor); + + return ( +
+ + + {isOpen && ( +
+ + {endpoint.examples.length > 0 && ( +
+
+ +
+
+ )} +
+ )} +
+ ); +} diff --git a/resources/js/components/api-docs/example-choice.ts b/resources/js/components/api-docs/example-choice.ts new file mode 100644 index 0000000000..579b7da0b5 --- /dev/null +++ b/resources/js/components/api-docs/example-choice.ts @@ -0,0 +1,20 @@ +import { createChoice } from '@/components/api-docs/choice'; + +const example = createChoice('api-docs:example'); + +export const chooseExample = example.choose; + +/** + * The client the reader picked last, such as Laravel: someone who picks it uses it, so every endpoint shows it. + */ +export const useChosenExample = example.useChosen; + +/** + * The tab to show: the one picked last when this endpoint has it, else the first. + */ +export function activeExample( + labels: string[], + chosenLabel: string | null, +): number { + return Math.max(0, chosenLabel === null ? 0 : labels.indexOf(chosenLabel)); +} diff --git a/resources/js/components/api-docs/example-tabs.tsx b/resources/js/components/api-docs/example-tabs.tsx new file mode 100644 index 0000000000..b0f1c714a6 --- /dev/null +++ b/resources/js/components/api-docs/example-tabs.tsx @@ -0,0 +1,175 @@ +import { useId } from 'react'; +import type { CSSProperties, KeyboardEvent } from 'react'; +import { flushSync } from 'react-dom'; +import { + activeExample, + chooseExample, + useChosenExample, +} from '@/components/api-docs/example-choice'; +import { CodeBlock } from '@/components/code-block'; +import { cn, withViewTransition } from '@/lib/utils'; +import type { ApiDocsExample } from '@/types'; + +/** + * The tab a key moves to, as a tab list's keys do: the arrows round the ends, Home and End to the ends. + */ +export function tabKeyTarget( + key: string, + active: number, + count: number, +): number | null { + switch (key) { + case 'ArrowRight': + return (active + 1) % count; + case 'ArrowLeft': + return (active - 1 + count) % count; + case 'Home': + return 0; + case 'End': + return count - 1; + default: + return null; + } +} + +/** + * Moves to the tab a key points at: picks it first, at once rather than after an animated transition, so the tab focus + * lands on is already the selected one and a next key counts from it. Says whether the key moved anything. + */ +export function moveToExample( + key: string, + active: number, + labels: string[], + pick: (label: string) => void, + focus: (index: number) => void, +): boolean { + const next = tabKeyTarget(key, active, labels.length); + const label = next === null ? undefined : labels[next]; + + if (next === null || label === undefined) { + return false; + } + + pick(label); + focus(next); + + return true; +} + +/** + * How to call an endpoint, one tab per client, the active one underlined in Commit Blue like the page tabs. Picking a + * client picks it on every endpoint, and next time too. + */ +export function ExampleTabs({ + examples, + holdHeight = true, +}: { + examples: ApiDocsExample[]; + holdHeight?: boolean; +}) { + const id = useId(); + // Each tab list on the page slides its own underline, so each needs a name of its own, as a CSS ident. + const indicatorName = `example-tab-${id.replace(/[^\w-]/g, '')}`; + const active = activeExample( + examples.map((example) => example.label), + useChosenExample(), + ); + const setActive = (index: number) => { + const label = examples[index]?.label; + + if (label !== undefined && index !== active) { + void withViewTransition(() => chooseExample(label)); + } + }; + + const onKeyDown = (event: KeyboardEvent) => { + const moved = moveToExample( + event.key, + active, + examples.map((example) => example.label), + (label) => flushSync(() => chooseExample(label)), + (index) => document.getElementById(`${id}-tab-${index}`)?.focus(), + ); + + if (moved) { + event.preventDefault(); + } + }; + + if (examples.length === 0) { + return null; + } + + return ( +
+
+ {examples.map((candidate, index) => ( + + ))} +
+ {/* Where the page renders on the server, every example sits in the same cell, so the tallest sets the + height and the server's first tab giving way to the reader's own client moves nothing. In a sticky + column, the height follows the example shown, or the hidden ones would hold it far below. */} +
+ {examples.map((candidate, index) => { + const isActive = index === active; + + return ( + + ); + })} +
+
+ ); +} diff --git a/resources/js/components/api-docs/field-table.tsx b/resources/js/components/api-docs/field-table.tsx new file mode 100644 index 0000000000..4e9b3e9759 --- /dev/null +++ b/resources/js/components/api-docs/field-table.tsx @@ -0,0 +1,116 @@ +import { ChevronRight } from 'lucide-react'; +import { Fragment, useState } from 'react'; +import { WARNING } from '@/components/api-docs/tones'; +import { cn } from '@/lib/utils'; +import type { ApiDocsField } from '@/types'; + +/** + * A description from the spec, with what it wraps in backticks set as code, as its docblock wrote it. + */ +export function SpecText({ text }: { text: string }) { + return ( + <> + {text.split(/(`[^`]+`)/).map((part, index) => ( + + {part.startsWith('`') && part.endsWith('`') ? ( + + {part.slice(1, -1)} + + ) : ( + part + )} + + ))} + + ); +} + +function FieldRow({ field }: { field: ApiDocsField }) { + const [isOpen, setIsOpen] = useState(false); + + return ( +
  • +
    + + {field.name} + + + {field.type} + + {field.required && ( + + required + + )} +
    + {field.description && ( +

    + +

    + )} + {field.enum && ( +

    + {field.enum.map((value) => ( + + {value} + + ))} +

    + )} + {field.children.length > 0 && ( + <> + + {isOpen && ( + + )} + + )} +
  • + ); +} + +/** + * What a request takes or an answer holds, field by field: its name and type in mono, whether it is required, what + * it means, the values it may take, and the fields inside it, folded until asked for. + */ +export function FieldTable({ + fields, + className, +}: { + fields: ApiDocsField[]; + className?: string; +}) { + return ( +
      + {fields.map((field) => ( + + ))} +
    + ); +} diff --git a/resources/js/components/api-docs/guide.tsx b/resources/js/components/api-docs/guide.tsx new file mode 100644 index 0000000000..7e77a01ba2 --- /dev/null +++ b/resources/js/components/api-docs/guide.tsx @@ -0,0 +1,128 @@ +import type { ReactNode } from 'react'; +import { CodeBlock } from '@/components/code-block'; +import { cn } from '@/lib/utils'; +import type { ApiDocsSnippet } from '@/types'; + +/** + * How wide the docs' content is, guides and reference alike, so moving between them never changes the page's width. + */ +export const DOCS_WIDTH = 'max-w-[1160px]'; + +/** + * A guide of the API docs, read like the site's other long pages: one Feed White sheet on the console's shell, as wide + * as the reference, its sections one after the other with a hairline between them, never a card each. + */ +export function Guide({ children }: { children: ReactNode }) { + return ( +
    + {children} +
    + ); +} + +function anchor(title: string): string { + return title + .toLowerCase() + .replace(/[^a-z0-9]+/g, '-') + .replace(/^-|-$/g, ''); +} + +/** + * A section of a guide, its title a link to itself, so a reader can point someone at it. + */ +export function GuideSection({ + title, + meta, + children, +}: { + title: string; + meta?: ReactNode; + children: ReactNode; +}) { + const id = anchor(title); + + return ( +
    +
    +

    + + {title} + +

    + {meta && ( + + {meta} + + )} +
    + {children} +
    + ); +} + +/** + * A guide's code, in the code block the reference and the rest of the docs use, highlighted by the server. + */ +export function Snippet({ snippet }: { snippet: ApiDocsSnippet | undefined }) { + if (snippet === undefined) { + return null; + } + + return ( + + ); +} + +export function Code({ children }: { children: ReactNode }) { + return ( + + {children} + + ); +} + +/** + * Named values in a hairline list, keys in mono, as the settings list what they show. + */ +export function FieldList({ + fields, + keyWidth = 'sm:grid-cols-[9rem_minmax(0,1fr)]', +}: { + fields: { name: string; children: ReactNode }[]; + keyWidth?: string; +}) { + return ( +
    + {fields.map((field) => ( +
    +
    + {field.name} +
    +
    {field.children}
    +
    + ))} +
    + ); +} diff --git a/resources/js/components/api-docs/schemas.ts b/resources/js/components/api-docs/schemas.ts new file mode 100644 index 0000000000..b50e8c5190 --- /dev/null +++ b/resources/js/components/api-docs/schemas.ts @@ -0,0 +1,73 @@ +import { useEffect, useSyncExternalStore } from 'react'; + +export type ApiDocsSchema = { code: string; html: string }; + +export type ApiDocsSchemas = { + body: ApiDocsSchema | null; + responses: Record; +}; + +export type SchemasState = ApiDocsSchemas | 'loading' | 'failed' | undefined; + +const loaded = new Map(); +const listeners = new Set<() => void>(); + +function notify(): void { + listeners.forEach((listener) => listener()); +} + +function subscribe(listener: () => void): () => void { + listeners.add(listener); + + return () => listeners.delete(listener); +} + +/** + * Asks for an endpoint's schemas once, and keeps them for every place on the page that shows them. Schemas that failed + * to load are asked for again, the failure showing until then. + */ +export async function loadSchemas(url: string): Promise { + const state = loaded.get(url); + + if (state !== undefined && state !== 'failed') { + return; + } + + loaded.set(url, 'loading'); + notify(); + + try { + const response = await fetch(url, { + headers: { Accept: 'application/json' }, + }); + + if (!response.ok) { + throw new Error(`${response.status}`); + } + + loaded.set(url, (await response.json()) as ApiDocsSchemas); + } catch { + loaded.set(url, 'failed'); + } + + notify(); +} + +/** + * An endpoint's schemas, asked for only while `url` is given, so a reader reading fields never loads them. + */ +export function useSchemas(url: string | null): SchemasState { + const state = useSyncExternalStore( + subscribe, + () => (url === null ? undefined : loaded.get(url)), + () => undefined, + ); + + useEffect(() => { + if (url !== null) { + void loadSchemas(url); + } + }, [url]); + + return state; +} diff --git a/resources/js/components/api-docs/search.ts b/resources/js/components/api-docs/search.ts new file mode 100644 index 0000000000..b5abbb8780 --- /dev/null +++ b/resources/js/components/api-docs/search.ts @@ -0,0 +1,74 @@ +import type { ApiDocsIndexEntry, ApiDocsSection } from '@/types'; + +export type ApiDocsResult = + | { kind: 'guide'; id: string; section: ApiDocsSection } + | { + kind: 'endpoint'; + id: string; + section: ApiDocsSection; + endpoint: ApiDocsIndexEntry; + }; + +/** + * The guides and endpoints whose words hold every word typed, in any order and case. What matches by its method, + * path or title comes before what only its summary mentions, and the docs' own order breaks ties. + */ +export function searchApiDocs( + query: string, + sections: ApiDocsSection[], + index: ApiDocsIndexEntry[], +): ApiDocsResult[] { + const words = query.toLowerCase().split(/\s+/).filter(Boolean); + const bySlug = new Map(sections.map((section) => [section.slug, section])); + + const candidates: { result: ApiDocsResult; name: string; text: string }[] = + [ + ...sections + .filter((section) => section.kind === 'guide') + .map((section) => ({ + result: { + kind: 'guide' as const, + id: section.slug, + section, + }, + name: section.title, + text: section.description, + })), + ...index.flatMap((endpoint) => { + const section = bySlug.get(endpoint.section); + + return section === undefined + ? [] + : [ + { + result: { + kind: 'endpoint' as const, + id: endpoint.id, + section, + endpoint, + }, + name: `${endpoint.method} ${endpoint.path} ${section.title}`, + text: endpoint.summary, + }, + ]; + }), + ]; + + return candidates + .map((candidate, order) => { + const name = candidate.name.toLowerCase(); + const text = candidate.text.toLowerCase(); + + return { + ...candidate, + order, + matches: words.every( + (word) => name.includes(word) || text.includes(word), + ), + score: words.filter((word) => name.includes(word)).length, + }; + }) + .filter((candidate) => candidate.matches) + .sort((a, b) => b.score - a.score || a.order - b.order) + .map((candidate) => candidate.result); +} diff --git a/resources/js/components/api-docs/tones.ts b/resources/js/components/api-docs/tones.ts new file mode 100644 index 0000000000..29dfe10cbb --- /dev/null +++ b/resources/js/components/api-docs/tones.ts @@ -0,0 +1,11 @@ +/** + * The console's status colors, tinted: a 10% wash, and text mixed with the ink so it stays readable at 12px. + */ +export const SUCCESS = + 'border-success/30 bg-success/10 text-[color-mix(in_oklab,var(--success)_70%,var(--foreground))]'; + +export const WARNING = + 'border-warning/30 bg-warning/10 text-[color-mix(in_oklab,var(--warning)_70%,var(--foreground))]'; + +export const DESTRUCTIVE = + 'border-destructive/30 bg-destructive/10 text-[color-mix(in_oklab,var(--destructive)_70%,var(--foreground))]'; diff --git a/resources/js/components/app-aside.tsx b/resources/js/components/app-aside.tsx index ac5f1184d5..48ffac7e0a 100644 --- a/resources/js/components/app-aside.tsx +++ b/resources/js/components/app-aside.tsx @@ -1,6 +1,7 @@ import { Link, usePage } from '@inertiajs/react'; import { Search } from 'lucide-react'; import AboutController from '@/actions/App/Http/Controllers/AboutController'; +import ApiDocsController from '@/actions/App/Http/Controllers/ApiDocsController'; import AppController from '@/actions/App/Http/Controllers/AppController'; import ChangelogController from '@/actions/App/Http/Controllers/ChangelogController'; import PartnerController from '@/actions/App/Http/Controllers/PartnerController'; @@ -114,6 +115,13 @@ export function AppAside({ > Apps + + API + + + + + API + + { + if (!isWaiting) { + return; + } + + const timer = window.setTimeout(() => setIsLate(true), delay); + + return () => { + window.clearTimeout(timer); + setIsLate(false); + }; + }, [isWaiting, delay]); + + return isWaiting && isLate; +} diff --git a/resources/js/layouts/api-docs/layout.tsx b/resources/js/layouts/api-docs/layout.tsx new file mode 100644 index 0000000000..d20e8f6824 --- /dev/null +++ b/resources/js/layouts/api-docs/layout.tsx @@ -0,0 +1,167 @@ +import { usePage } from '@inertiajs/react'; +import type { LucideIcon } from 'lucide-react'; +import { + Bell, + BookOpen, + Bug, + Building2, + CalendarClock, + CircleAlert, + CircleUser, + FileJson, + Flame, + Gauge, + GitCommitHorizontal, + KeyRound, + ListOrdered, + MessagesSquare, + Search, + Users, +} from 'lucide-react'; +import { useEffect, useRef, useState } from 'react'; +import type { PropsWithChildren } from 'react'; +import OpenApiController from '@/actions/App/Http/Controllers/Api/OpenApiController'; +import ApiDocsController from '@/actions/App/Http/Controllers/ApiDocsController'; +import LogController from '@/actions/App/Http/Controllers/LogController'; +import { + EndpointSearch, + isSearchShortcut, +} from '@/components/api-docs/endpoint-search'; +import ConsoleLayout from '@/layouts/console/layout'; +import type { ConsoleNavGroup } from '@/layouts/console/layout'; +import { useKeyLabels } from '@/lib/keyboard'; +import { home } from '@/routes'; +import type { ApiDocsProps, ApiDocsSection } from '@/types'; + +const ICONS: Record = { + introduction: BookOpen, + authentication: KeyRound, + 'rate-limits': Gauge, + pagination: ListOrdered, + errors: CircleAlert, + users: Users, + commits: GitCommitHorizontal, + organizations: Building2, + me: CircleUser, + search: Search, + 'scheduled-commits': CalendarClock, + remotes: MessagesSquare, + notifications: Bell, + headlines: Flame, + issues: Bug, +}; + +function navItems(sections: ApiDocsSection[]) { + return sections.map((section) => ({ + key: section.slug, + title: section.title, + description: section.description, + href: ApiDocsController.show(section.slug), + icon: ICONS[section.slug] ?? BookOpen, + })); +} + +/** + * The API docs as a console beside the log: the guides and the groups of the reference in the sidebar, and the spec + * they are read from elsewhere. + */ +export default function ApiDocsLayout({ children }: PropsWithChildren) { + const { props } = usePage(); + const keys = useKeyLabels(); + const [isSearching, setIsSearching] = useState(false); + const searchButton = useRef(null); + + useEffect(() => { + const onKeyDown = (event: KeyboardEvent) => { + if (isSearchShortcut(event)) { + event.preventDefault(); + setIsSearching(true); + } + }; + + window.addEventListener('keydown', onKeyDown); + + return () => window.removeEventListener('keydown', onKeyDown); + }, []); + + const groups: ConsoleNavGroup[] = [ + { + label: 'Guide', + items: navItems( + props.sections.filter((section) => section.kind === 'guide'), + ), + }, + { + label: 'Reference', + items: navItems( + props.sections.filter( + (section) => section.kind === 'reference', + ), + ), + }, + { + label: 'Elsewhere', + items: [ + { + key: 'openapi', + title: 'openapi.json', + description: 'The whole API as OpenAPI 3.1', + href: OpenApiController.show().url, + icon: FileJson, + external: true, + }, + ], + }, + ]; + + return ( + <> + + + v1 + + + + } + > + {children} + + searchButton.current?.focus()} + /> + + ); +} diff --git a/resources/js/layouts/console/layout.tsx b/resources/js/layouts/console/layout.tsx new file mode 100644 index 0000000000..1e829b9ca0 --- /dev/null +++ b/resources/js/layouts/console/layout.tsx @@ -0,0 +1,284 @@ +import { Link } from '@inertiajs/react'; +import type { InertiaLinkProps } from '@inertiajs/react'; +import type { LucideIcon } from 'lucide-react'; +import { ArrowUpRight } from 'lucide-react'; +import { useEffect, useRef } from 'react'; +import type { ReactNode } from 'react'; +import AppLogoIcon from '@/components/app-logo-icon'; +import AppWordmark from '@/components/app-wordmark'; +import AppearanceToggleTab from '@/components/appearance-tabs'; +import { UserAvatar } from '@/components/user-avatar'; +import { cn } from '@/lib/utils'; +import type { User } from '@/types'; + +export type ConsoleNavItem = { + key: string; + title: string; + description: string; + href: NonNullable; + icon: LucideIcon; + external?: boolean; +}; + +export type ConsoleNavGroup = { + label: string; + items: ConsoleNavItem[]; +}; + +const itemClassName = + 'flex h-9 shrink-0 items-center gap-2.5 rounded-lg px-2.5 text-sm font-medium whitespace-nowrap text-muted-foreground transition-colors hover:bg-accent hover:text-foreground'; + +function NavItem({ + item, + isActive, + prefetch, +}: { + item: ConsoleNavItem; + isActive: boolean; + prefetch: boolean; +}) { + if (item.external) { + return ( + + + {item.title} + + + ); + } + + return ( + + + {item.title} + + ); +} + +function Brand({ + chip, + label, + href, + prefetch, +}: { + chip: string; + label: string; + href: NonNullable; + prefetch: boolean; +}) { + return ( + + + + + {chip} + + + ); +} + +/** + * The shell of a standalone console beside the log, such as Operations: a sidebar of grouped pages, a header naming + * the current one, and a way back to /dev/null. Its pages prefetch on hover only when the console asks for it. + */ +export default function ConsoleLayout({ + chip, + label, + navLabel, + brandHref, + prefetch = false, + groups, + current, + backHref, + user, + headerActions, + children, +}: { + chip: string; + label: string; + navLabel: string; + brandHref: NonNullable; + prefetch?: boolean; + groups: ConsoleNavGroup[]; + current: string; + backHref: string; + user: User | null; + headerActions?: ReactNode; + children: ReactNode; +}) { + const items = groups.flatMap((group) => group.items); + const page = items.find((item) => item.key === current && !item.external); + const mobileNav = useRef(null); + + useEffect(() => { + mobileNav.current + ?.querySelector('[aria-current="page"]') + ?.scrollIntoView({ block: 'nearest', inline: 'nearest' }); + }, [current]); + + return ( +
    + + +
    +
    +
    +
    + +
    +
    +

    + {page?.title ?? navLabel} +

    +

    + {page?.description} +

    +
    + +
    + {headerActions} + + {user ? ( + + ) : ( + + )} + +
    +
    + + +
    + +
    +
    +

    + {page?.title ?? navLabel} +

    +

    + {page?.description} +

    +
    + {children} +
    +
    +
    + ); +} diff --git a/resources/js/layouts/operations/layout.tsx b/resources/js/layouts/operations/layout.tsx index e8c7c913e3..22548ec0ec 100644 --- a/resources/js/layouts/operations/layout.tsx +++ b/resources/js/layouts/operations/layout.tsx @@ -1,9 +1,6 @@ -import { Link, router, usePage, usePoll } from '@inertiajs/react'; -import type { InertiaLinkProps } from '@inertiajs/react'; -import type { LucideIcon } from 'lucide-react'; +import { router, usePage, usePoll } from '@inertiajs/react'; import { Activity, - ArrowUpRight, ChartNoAxesCombined, Flag, Gauge, @@ -18,7 +15,7 @@ import { ShieldCheck, TrendingUp, } from 'lucide-react'; -import { useEffect, useRef, useState } from 'react'; +import { useState } from 'react'; import type { PropsWithChildren } from 'react'; import EmailController from '@/actions/App/Http/Controllers/EmailController'; import FeatureController from '@/actions/App/Http/Controllers/FeatureController'; @@ -31,13 +28,11 @@ import ProductMetricsController from '@/actions/App/Http/Controllers/ProductMetr import SiteActivityController from '@/actions/App/Http/Controllers/SiteActivityController'; import SystemHealthController from '@/actions/App/Http/Controllers/SystemHealthController'; import TrafficController from '@/actions/App/Http/Controllers/TrafficController'; -import AppLogoIcon from '@/components/app-logo-icon'; -import AppWordmark from '@/components/app-wordmark'; -import AppearanceToggleTab from '@/components/appearance-tabs'; import { ChatDock } from '@/components/chat/chat-dock'; import { Button } from '@/components/ui/button'; -import { UserAvatar } from '@/components/user-avatar'; import { useRemoteAlerts, useRemoteUpdates } from '@/hooks/use-chat'; +import ConsoleLayout from '@/layouts/console/layout'; +import type { ConsoleNavGroup } from '@/layouts/console/layout'; import { backgroundPollOptions } from '@/lib/background-poll'; import { cn } from '@/lib/utils'; import { home } from '@/routes'; @@ -104,35 +99,27 @@ const POLL_PROPS = Object.fromEntries( ]), ) as Record; -type NavEntry = { - page: OperationsPage; - title: string; - description: string; - href: NonNullable; - icon: LucideIcon; -}; - -function navGroups(): { label: string; items: NavEntry[] }[] { +function navGroups(): ConsoleNavGroup[] { return [ { label: 'Monitor', items: [ { - page: 'operations/show', + key: 'operations/show', title: 'Overview', description: 'What needs attention, and what is fine', href: OperationsController.show(), icon: LayoutDashboard, }, { - page: 'operations/health', + key: 'operations/health', title: 'Health', description: 'Services, queues, failed jobs and backlogs', href: SystemHealthController.show(), icon: HeartPulse, }, { - page: 'operations/events', + key: 'operations/events', title: 'Events', description: 'Everything that happened, newest first', href: OperationsEventController.index(), @@ -144,28 +131,28 @@ function navGroups(): { label: string; items: NavEntry[] }[] { label: 'Product', items: [ { - page: 'operations/forecasts', + key: 'operations/forecasts', title: 'Forecasts', description: 'Where the trends are heading next', href: ForecastController.show(), icon: TrendingUp, }, { - page: 'operations/metrics', + key: 'operations/metrics', title: 'Growth', description: 'Acquisition, activation and retention', href: ProductMetricsController.show(), icon: ChartNoAxesCombined, }, { - page: 'operations/activity', + key: 'operations/activity', title: 'Activity', description: 'Commits, replies and signups over time', href: SiteActivityController.show(), icon: Activity, }, { - page: 'operations/traffic', + key: 'operations/traffic', title: 'Traffic', description: 'Visitors and where they come from', href: TrafficController.show(), @@ -177,14 +164,14 @@ function navGroups(): { label: string; items: NavEntry[] }[] { label: 'Control', items: [ { - page: 'operations/features', + key: 'operations/features', title: 'Features', description: 'Choose who can use each feature', href: FeatureController.index(), icon: Flag, }, { - page: 'operations/emails', + key: 'operations/emails', title: 'Emails', description: 'Write to everyone, or the people you pick', href: EmailController.create(), @@ -192,6 +179,19 @@ function navGroups(): { label: string; items: NavEntry[] }[] { }, ], }, + { + label: 'Elsewhere', + items: [ + { + key: 'moderation', + title: 'Moderation', + description: 'Commits waiting for review', + href: ModerationController.show().url, + icon: ShieldCheck, + external: true, + }, + ], + }, ]; } @@ -201,41 +201,6 @@ function Poll({ only }: { only: string[] }) { return null; } -function NavItem({ item, isActive }: { item: NavEntry; isActive: boolean }) { - return ( - - - {item.title} - - ); -} - -function Brand() { - return ( - - - - - ops - - - ); -} - export default function OperationsLayout({ children }: PropsWithChildren) { const { component, props } = usePage(); const page = component as OperationsPage; @@ -243,26 +208,16 @@ export default function OperationsLayout({ children }: PropsWithChildren) { const [isLive, setIsLive] = useState(true); const only = PAGE_PROPS[page] ?? []; const polls = !ON_DEMAND.includes(page); - const groups = navGroups(); - const items = groups.flatMap((group) => group.items); - const current = items.find((item) => item.page === page); const user = props.auth.user; const hasRemotes = user !== null && props.auth.remotes !== null; const backHref = props.auth.log === null ? home().url : LogController.show(props.auth.log).url; - const mobileNav = useRef(null); useRemoteAlerts(hasRemotes ? user.id : null); useRemoteUpdates(hasRemotes ? user.id : null); - useEffect(() => { - mobileNav.current - ?.querySelector('[aria-current="page"]') - ?.scrollIntoView({ block: 'nearest', inline: 'nearest' }); - }, [page]); - const refresh = () => { if (isRefreshing) { return; @@ -285,226 +240,84 @@ export default function OperationsLayout({ children }: PropsWithChildren) { }; return ( -
    + <> {polls && isLive && ( )} - - -
    -
    -
    -
    - -
    -
    -

    - {current?.title ?? 'Operations'} -

    -

    - {current?.description} -

    -
    - -
    - {polls ? ( - - ) : ( - - - on demand - - )} + + {polls ? ( - {user && ( - - - - )} -
    -
    - - -
    - -
    -
    -

    - {current?.title ?? 'Operations'} -

    -

    - {current?.description} -

    -
    - {children} -
    -
    + + + + } + > + {children} + {hasRemotes && } -
    + ); } diff --git a/resources/js/pages/api-docs/guides/authentication.tsx b/resources/js/pages/api-docs/guides/authentication.tsx new file mode 100644 index 0000000000..32806cde56 --- /dev/null +++ b/resources/js/pages/api-docs/guides/authentication.tsx @@ -0,0 +1,185 @@ +import { ExampleTabs } from '@/components/api-docs/example-tabs'; +import { + Code, + FieldList, + Guide, + GuideSection, + Snippet, +} from '@/components/api-docs/guide'; +import type { ApiDocsExample, ApiDocsSnippet } from '@/types'; + +export function Authentication({ + signing, + snippets, +}: { + signing: ApiDocsExample[]; + snippets: Record; +}) { + return ( + + + +

    Each endpoint of the reference says which it is.

    +
    + + +

    + Your app keeps its own SSH key, made for it. It doesn't need + to be on anyone's GitHub account, and a key that is only on + GitHub can't sign API requests. +

    + +

    + Then open https://dev-null.sh/mobile/authorize{' '} + in a browser, the way an OAuth app would, with PKCE: +

    + + The key's, as ssh-keygen -lf{' '} + prints it: SHA256:… + + ), + }, + { + name: 'device_name', + children: + 'Where the key lives, shown on the approval page', + }, + { + name: 'app_name', + children: + 'Optional. Your app, so people can tell apps apart in their devices', + }, + { + name: 'app_id', + children: ( + <> + Optional. A stable platform and identifier, + like macos:sh.dev-null.mac + + ), + }, + { + name: 'code_challenge', + children: ( + <> + The SHA-256 of your verifier, base64url + without padding, 43 characters, with{' '} + code_challenge_method=S256 + + ), + }, + { + name: 'state', + children: 'Anything, sent back as it is', + }, + { + name: 'redirect_uri', + children: ( + <> + Where the code goes:{' '} + http://127.0.0.1:<port>{' '} + your app listens on. devnull://{' '} + is the /dev/null apps' own. + + ), + }, + ]} + /> +

    + The person signs in with GitHub if they need to, checks the + fingerprint and approves. The browser then goes to your{' '} + redirect_uri with a code and your{' '} + state, or with error=access_denied + . Redeem the code with POST /devices, signed + with the new key, its body{' '} + {'{"code": "…", "code_verifier": "…"}'}. The + key is now one of their devices, until they revoke it in + Settings → Devices. +

    +

    + Only signing in uses POST /devices, so the + reference leaves it out with the other endpoints only the + apps need to work. +

    +
    + + +

    + Every request signs these five lines with the key, as an SSH + signature in the devnull-api namespace: +

    + + +

    + The path and query are exactly the ones you request, from + the root: /api/v1/search/commits?q=laravel. The + body is exactly the bytes you send, as JSON with{' '} + Content-Type: application/json, or nothing when + there is none. +

    +

    + Every signed example of the reference calls one of these, + with its method, path and body: +

    + +

    + A request with images or a voice note is multipart, with + nothing else in it: the JSON as a payload file + part of type application/json (with curl,{' '} + -F 'payload=@body.json;type=application/json' + ), and either the images in images[] or the + voice note in voice, never both. The signed + message then has one more line before the body, the SHA-256 + of each file, in hex, comma separated in the order they are + attached, and the namespace is{' '} + devnull-api-images. +

    +
    + + +

    + Someone has to accept the commit rules once, in the web + composer, before an app can commit for them. Until then, + commits answer commit_rules_required. +

    +
    +
    + ); +} diff --git a/resources/js/pages/api-docs/guides/errors.tsx b/resources/js/pages/api-docs/guides/errors.tsx new file mode 100644 index 0000000000..34b0ec327f --- /dev/null +++ b/resources/js/pages/api-docs/guides/errors.tsx @@ -0,0 +1,78 @@ +import { + Code, + Guide, + GuideSection, + Snippet, +} from '@/components/api-docs/guide'; +import type { ApiDocsSnippet, ApiErrorCodeStatus } from '@/types'; + +export function Errors({ + codes, + snippets, +}: { + codes: ApiErrorCodeStatus[]; + snippets: Record; +}) { + return ( + + +

    + Every error says what happened in message, in + the web's own words. An error the API answers itself, listed + below, also says which one it is in code. A + code never changes once released: match on it, and show the + message. +

    +

    + Laravel's own errors have no code: a{' '} + 404 for something that doesn't exist or isn't + yours to see, a 403 for an action you can't + take, and validation errors, which also say what is wrong + with each field in errors, below. +

    + +
    + + +
    + + + + + + + + + + {codes.map(({ code, status, meaning }) => ( + + + + + + ))} + +
    + status + code + meaning +
    + {status} + + {code} + + {meaning} +
    +
    +
    + + +

    + A request that doesn't pass validation is a 422 + , with what is wrong with each field, as Laravel answers it: +

    + +
    +
    + ); +} diff --git a/resources/js/pages/api-docs/guides/introduction.tsx b/resources/js/pages/api-docs/guides/introduction.tsx new file mode 100644 index 0000000000..1de37dc2fb --- /dev/null +++ b/resources/js/pages/api-docs/guides/introduction.tsx @@ -0,0 +1,96 @@ +import { Link } from '@inertiajs/react'; +import OpenApiController from '@/actions/App/Http/Controllers/Api/OpenApiController'; +import ApiDocsController from '@/actions/App/Http/Controllers/ApiDocsController'; +import { + Code, + FieldList, + Guide, + GuideSection, + Snippet, +} from '@/components/api-docs/guide'; +import type { ApiDocsSnippet } from '@/types'; + +const API_URL = 'https://dev-null.sh/api/v1'; + +export function Introduction({ + snippets, +}: { + snippets: Record; +}) { + return ( + + +

    + The JSON API the /dev/null apps use, open to anything you + build: a bot, a bridge, a widget on your own site. +

    +

    + Reading public profiles and commits needs nothing. Acting + for someone needs their approval and a signature on every + request: there are no passwords and no API tokens. +

    + {API_URL} }, + { + name: 'format', + children: + 'JSON, or multipart when a request carries images or a voice note', + }, + { + name: 'accept', + children: ( + <> + Accept: application/json on + every request, so every error comes back as + JSON + + ), + }, + { + name: 'spec', + children: ( + <> + + OpenAPI 3.1 + + , generated from the code, so it changes + when the API does + + ), + }, + ]} + /> +
    + + +

    A profile, as anyone can read it:

    + +

    + Lists come a page at a time: see{' '} + + Pagination + + . To read what someone sees, or to commit for them, sign the + request: see{' '} + + Authentication + + . +

    +
    + + +

    + A signed request sees what the web shows the person who + signed it, and goes through the same validation, moderation + and limits: a commit may come back pending, and a blocked + profile stays out of reach. +

    +
    +
    + ); +} diff --git a/resources/js/pages/api-docs/guides/pagination.tsx b/resources/js/pages/api-docs/guides/pagination.tsx new file mode 100644 index 0000000000..8f1411982b --- /dev/null +++ b/resources/js/pages/api-docs/guides/pagination.tsx @@ -0,0 +1,58 @@ +import { + Code, + Guide, + GuideSection, + Snippet, +} from '@/components/api-docs/guide'; +import type { ApiDocsSnippet } from '@/types'; + +export function Pagination({ + snippets, +}: { + snippets: Record; +}) { + return ( + + +

    + Lists are cursor-paginated, newest first, 20 a page. A + cursor marks where the page ended, so commits arriving + meanwhile never push the next page back. +

    + +

    + Follow links.next until it is null + , or pass meta.next_cursor as{' '} + cursor yourself. Keep the other parameters of + the first request: the links already do. +

    +
    + + +
      +
    • + Followers, following and followed organizations come 30 + a page. +
    • +
    • + A commit's replies come 50 a page, oldest first, or + newest first with newest=1. +
    • +
    • + A log ranked by something else than time keeps its + rank's order. Asked to reach back to a commit you + already have, a log or the notifications send every one + since, so a page can hold more than 20. +
    • +
    • + Scheduled commits come by page number, 20 a page, drafts + not yet submitted first, then the soonest:{' '} + links.next works the same, and{' '} + meta also has current_page,{' '} + last_page and total. +
    • +
    +
    +
    + ); +} diff --git a/resources/js/pages/api-docs/guides/rate-limits.tsx b/resources/js/pages/api-docs/guides/rate-limits.tsx new file mode 100644 index 0000000000..d6cbef0157 --- /dev/null +++ b/resources/js/pages/api-docs/guides/rate-limits.tsx @@ -0,0 +1,60 @@ +import { Code, Guide, GuideSection } from '@/components/api-docs/guide'; +import type { ApiRateLimit } from '@/types'; + +export function RateLimits({ limits }: { limits: ApiRateLimit[] }) { + return ( + + +

    + Every request counts toward one of the first two: unsigned + requests by address, signed ones by the person who signed. + Some actions have a budget of their own on top, the same as + on the web. +

    +
    + + + + + + + + + + {limits.map((row) => ( + + + + + + ))} + +
    what + limit + per
    {row.what} + {row.limit} + + {row.per} +
    +
    +
    + + +

    + Every answer says where you are in the first two in{' '} + X-RateLimit-Limit and{' '} + X-RateLimit-Remaining; an action's own budget + isn't in them. Past any limit, the answer is a{' '} + 429 with Retry-After, the seconds + to wait, and a message. +

    +

    + A signed request also gets the code{' '} + rate_limited, except past the pings and commit + searches budgets, which only say it in their message. An + unsigned request never gets a code. +

    +
    +
    + ); +} diff --git a/resources/js/pages/api-docs/show.tsx b/resources/js/pages/api-docs/show.tsx new file mode 100644 index 0000000000..44f7e50d4e --- /dev/null +++ b/resources/js/pages/api-docs/show.tsx @@ -0,0 +1,53 @@ +import { Head, usePage } from '@inertiajs/react'; +import { Endpoint } from '@/components/api-docs/endpoint'; +import { DOCS_WIDTH } from '@/components/api-docs/guide'; +import ApiDocsLayout from '@/layouts/api-docs/layout'; +import { cn } from '@/lib/utils'; +import { Authentication } from '@/pages/api-docs/guides/authentication'; +import { Errors } from '@/pages/api-docs/guides/errors'; +import { Introduction } from '@/pages/api-docs/guides/introduction'; +import { Pagination } from '@/pages/api-docs/guides/pagination'; +import { RateLimits } from '@/pages/api-docs/guides/rate-limits'; +import type { ApiDocsProps } from '@/types'; + +export default function Show() { + const { + sections, + current, + endpoints, + errorCodes, + rateLimits, + signing, + snippets, + } = usePage().props; + const section = sections.find((candidate) => candidate.slug === current); + + return ( + <> + + + {current === 'introduction' && } + {current === 'authentication' && ( + + )} + {current === 'rate-limits' && } + {current === 'pagination' && } + {current === 'errors' && ( + + )} + {section?.kind === 'reference' && ( +
    + {endpoints.map((endpoint) => ( + + ))} +
    + )} + + ); +} + +Show.layout = ApiDocsLayout; diff --git a/resources/js/types/api-docs.ts b/resources/js/types/api-docs.ts new file mode 100644 index 0000000000..75889ce32c --- /dev/null +++ b/resources/js/types/api-docs.ts @@ -0,0 +1,79 @@ +export type ApiDocsSection = { + slug: string; + title: string; + description: string; + kind: 'guide' | 'reference'; +}; + +export type ApiErrorCodeStatus = { + code: string; + status: number; + meaning: string; +}; + +export type ApiDocsSnippet = { + language: string; + html: string; +}; + +export type ApiRateLimit = { + what: string; + limit: number; + per: string; +}; + +export type ApiDocsField = { + name: string; + type: string; + required: boolean; + description: string | null; + enum: (string | number)[] | null; + children: ApiDocsField[]; +}; + +export type ApiDocsParameter = ApiDocsField & { in: string }; + +export type ApiDocsResponse = { + status: string; + description: string; + fields: ApiDocsField[]; +}; + +export type ApiDocsEndpoint = { + id: string; + method: string; + path: string; + summary: string; + description: string | null; + signature: 'required' | 'optional'; + parameters: ApiDocsParameter[]; + body: { mediaType: string; fields: ApiDocsField[] } | null; + responses: ApiDocsResponse[]; + examples: ApiDocsExample[]; +}; + +export type ApiDocsExample = { + label: string; + language: string; + code: string; + html: string; +}; + +export type ApiDocsIndexEntry = { + id: string; + method: string; + path: string; + summary: string; + section: string; +}; + +export type ApiDocsProps = { + sections: ApiDocsSection[]; + current: string; + endpoints: ApiDocsEndpoint[]; + index: ApiDocsIndexEntry[]; + signing: ApiDocsExample[]; + rateLimits: ApiRateLimit[]; + snippets: Record; + errorCodes: ApiErrorCodeStatus[]; +}; diff --git a/resources/js/types/index.ts b/resources/js/types/index.ts index f7facc21a5..e585011f25 100644 --- a/resources/js/types/index.ts +++ b/resources/js/types/index.ts @@ -1,4 +1,5 @@ export type * from './achievement'; +export type * from './api-docs'; export type * from './activity'; export type * from './auth'; export type * from './commit'; diff --git a/routes/api.php b/routes/api.php index 0b6b1f79ec..bc9b335723 100644 --- a/routes/api.php +++ b/routes/api.php @@ -45,6 +45,7 @@ use App\Http\Controllers\Api\MessageVoiceController; use App\Http\Controllers\Api\NotificationController; use App\Http\Controllers\Api\NotificationGroupController; +use App\Http\Controllers\Api\OpenApiController; use App\Http\Controllers\Api\OrganizationAdminController; use App\Http\Controllers\Api\OrganizationCommitController; use App\Http\Controllers\Api\OrganizationController; @@ -137,6 +138,11 @@ // The Mac app's latest release, which its update check compares with, unsigned so it sends nothing about anyone... Route::get('apps/mac', [MacAppController::class, 'show'])->name('api-mac-app.show'); + // This API's OpenAPI spec, for anyone building on it... + Route::get('openapi.json', [OpenApiController::class, 'show']) + ->middleware('cache.headers:public;max_age=3600;etag') + ->name('api-openapi.show'); + // Signing in: the app redeems the code it got on the web, signed with a key that isn't approved yet... Route::post('devices', [DeviceController::class, 'store']) ->withoutMiddleware('throttle:api') diff --git a/routes/web.php b/routes/web.php index 15be6e4484..df374ee339 100644 --- a/routes/web.php +++ b/routes/web.php @@ -2,9 +2,12 @@ declare(strict_types=1); +use App\Enums\ApiDocsSection; use App\Enums\Log; use App\Enums\ProfileType; use App\Http\Controllers\AboutController; +use App\Http\Controllers\ApiDocsController; +use App\Http\Controllers\ApiDocsSchemaController; use App\Http\Controllers\AppController; use App\Http\Controllers\BanController; use App\Http\Controllers\BannedController; @@ -245,6 +248,18 @@ // What was merged into production, readable by everyone... Route::get('changelog', [ChangelogController::class, 'index'])->name('changelog.index'); +// The API docs, readable by everyone... +Route::redirect('docs/api', '/docs/api/'.ApiDocsSection::Introduction->value)->name('api-docs.index'); +Route::get('docs/api/{section}', [ApiDocsController::class, 'show'])->name('api-docs.show'); +// An endpoint's schemas are the same for everyone, so they skip the web group's session and cookies, which would keep a +// cache from sharing them, and its route bindings with them: the section is read by the controller... +Route::get('docs/api/{section}/schemas/{endpoint}', [ApiDocsSchemaController::class, 'show']) + ->withoutMiddleware('web') + ->middleware('cache.headers:public;max_age=3600;etag') + ->whereIn('section', array_column(ApiDocsSection::cases(), 'value')) + ->where('endpoint', '[A-Za-z0-9._-]{1,100}') + ->name('api-docs-schema.show'); + // Public pages, readable by guests and crawlers... Route::middleware([RememberIntendedUrl::class, RedirectToHandleCase::class])->group(function (): void { // A handle no user has may be an organization's, an unclaimed developer's, or one to look up on GitHub. Bindings diff --git a/tests/Feature/ApiSigningGuideTest.php b/tests/Feature/ApiSigningGuideTest.php new file mode 100644 index 0000000000..6f33c4d514 --- /dev/null +++ b/tests/Feature/ApiSigningGuideTest.php @@ -0,0 +1,87 @@ +throw(); + + Device::factory()->for($user)->withPublicKey(SshPublicKey::fromOpenSsh(File::get("{$home}/.ssh/devnull.pub")))->create(); + + return $home; +} + +/** + * The headers one of the guide's signing helpers makes, run as the guide shows it, with that home. + * + * @return array + */ +function signingGuideHeaders(string $client, string $home, string $method, string $path, string $body): array +{ + $helpers = array_column(resolve(ApiExamples::class)->signing(), 'code', 'label'); + + if ($client === 'Laravel') { + if (! function_exists('SigningGuide\devnullHeaders')) { + eval("namespace SigningGuide;\n".$helpers['Laravel']); + } + + $previous = getenv('HOME'); + putenv("HOME={$home}"); + $headers = devnullHeaders($method, $path, $body); + putenv("HOME={$previous}"); + + return $headers; + } + + if ($client === 'curl') { + $script = $helpers['curl']."\ndevnull_sign \"\$1\" \"\$2\" \"\$3\"\nprintf '%s\\n%s\\n%s' \"\$ts\" \"\$nonce\" \"\$signature\""; + [$timestamp, $nonce, $signature] = explode("\n", Process::env(['HOME' => $home])->run(['bash', '-c', $script, 'sign', $method, $path, $body])->throw()->output()); + + return ['X-Devnull-Timestamp' => $timestamp, 'X-Devnull-Nonce' => $nonce, 'X-SSH-Signature' => $signature]; + } + + File::put("{$home}/devnull.mjs", $helpers['fetch']); + $script = "import { devnullHeaders } from '{$home}/devnull.mjs'; const [method, path, body] = process.argv.slice(1); process.stdout.write(JSON.stringify(devnullHeaders(method, path, body)));"; + + return json_decode(Process::env(['HOME' => $home])->run(['node', '--input-type=module', '-e', $script, $method, $path, $body])->throw()->output(), true, flags: JSON_THROW_ON_ERROR); +} + +it("signs requests the API accepts with each client's helper from the guide", function (string $client): void { + $user = User::factory()->create(); + $followed = User::factory()->create(); + $home = signingGuideHome($user); + + $requests = [ + ['GET', '/api/v1/me', ''], + ['POST', "/api/v1/users/{$followed->handle}/follow", ''], + ['POST', '/api/v1/commits/preview', (string) json_encode(['body' => 'Hello from the API!'])], + ]; + + foreach ($requests as [$method, $path, $body]) { + $headers = signingGuideHeaders($client, $home, $method, $path, $body); + $server = ['CONTENT_TYPE' => 'application/json', 'HTTP_ACCEPT' => 'application/json']; + + foreach ($headers as $name => $value) { + $server['HTTP_'.Str::upper(Str::replace('-', '_', $name))] = $value; + } + + $this->call($method, $path, server: $server, content: $body)->assertSuccessful(); + } + + File::deleteDirectory($home); +})->with(['curl', 'Laravel', 'fetch']); diff --git a/tests/Feature/Controllers/Api/OpenApiControllerTest.php b/tests/Feature/Controllers/Api/OpenApiControllerTest.php new file mode 100644 index 0000000000..19a35ffe51 --- /dev/null +++ b/tests/Feature/Controllers/Api/OpenApiControllerTest.php @@ -0,0 +1,21 @@ +get(route('api-openapi.show'))->assertOk(); + + expect($response->headers->get('Content-Type'))->toBe('application/json') + ->and($response->getContent())->toBe(file_get_contents(resource_path('api/openapi.json'))); +}); + +it('lets clients and caches keep the spec for an hour', function (): void { + $response = $this->get(route('api-openapi.show'))->assertOk(); + + expect($response->headers->get('Cache-Control'))->toContain('public', 'max-age=3600') + ->and($response->headers->get('ETag'))->not->toBeNull(); +}); + +it('lives beside the API it describes', function (): void { + expect(route('api-openapi.show', absolute: false))->toBe('/api/v1/openapi.json'); +}); diff --git a/tests/Feature/Controllers/ApiDocsControllerTest.php b/tests/Feature/Controllers/ApiDocsControllerTest.php new file mode 100644 index 0000000000..f561f71078 --- /dev/null +++ b/tests/Feature/Controllers/ApiDocsControllerTest.php @@ -0,0 +1,150 @@ +get('/docs/api')->assertRedirect(route('api-docs.show', ApiDocsSection::Introduction)); +}); + +it('renders every section of the API docs for guests', function (ApiDocsSection $section): void { + $this->get(route('api-docs.show', $section)) + ->assertOk() + ->assertInertia(fn ($page) => $page->component('api-docs/show') + ->where('current', $section->value)); +})->with(ApiDocsSection::cases()); + +it('renders the API docs for signed in users', function (): void { + $this->actingAs(User::factory()->create()) + ->get(route('api-docs.show', ApiDocsSection::Users)) + ->assertOk() + ->assertInertia(fn ($page) => $page->component('api-docs/show')); +}); + +it('lists the guides in reading order, then the groups of the reference alphabetically', function (): void { + $this->get(route('api-docs.show', ApiDocsSection::Introduction)) + ->assertInertia(fn ($page) => $page + ->has('sections', 15) + ->where('sections.0', [ + 'slug' => 'introduction', + 'title' => 'Introduction', + 'description' => 'What the API is for, and where it lives', + 'kind' => 'guide', + ]) + ->where('sections.4.slug', 'errors') + ->where('sections.5', [ + 'slug' => 'commits', + 'title' => 'Commits', + 'description' => 'Reading, writing, starring and replying to commits', + 'kind' => 'reference', + ]) + ->where('sections', fn ($sections): bool => collect($sections)->slice(5)->pluck('slug')->all() === [ + 'commits', 'headlines', 'issues', 'me', 'notifications', 'organizations', 'remotes', 'scheduled-commits', 'search', 'users', + ])); +}); + +it('lists the endpoints of a group of the reference', function (): void { + $this->get(route('api-docs.show', ApiDocsSection::Users)) + ->assertInertia(fn ($page) => $page + ->where('endpoints.0.method', 'GET') + ->where('endpoints.0.path', '/users/{handle}') + ->where('endpoints.0.signature', 'optional')); +}); + +it('indexes every endpoint on every page, for searching them', function (): void { + $this->get(route('api-docs.show', ApiDocsSection::Introduction)) + ->assertInertia(fn ($page) => $page + ->has('index', count(resolve(ApiDocsQuery::class)->index())) + ->where('index.0.section', 'commits') + ->where('index.0.path', '/commits/{commit}')); +}); + +it('sends the index once, leaving it out of the pages a visit goes on to', function (): void { + $this->get(route('api-docs.show', ApiDocsSection::Commits), [ + 'X-Inertia' => 'true', + 'X-Inertia-Version' => (string) resolve(HandleInertiaRequests::class)->version(request()), + 'X-Inertia-Except-Once-Props' => 'index', + ])->assertOk()->assertJsonMissingPath('props.index'); +}); + +it("gives a guide its code blocks, and the reference's groups none", function (): void { + $this->get(route('api-docs.show', ApiDocsSection::Errors)) + ->assertInertia(fn ($page) => $page + ->has('snippets', 2) + ->has('snippets.error', fn ($snippet) => $snippet->where('language', 'json')->has('html'))); + + $this->get(route('api-docs.show', ApiDocsSection::Users)) + ->assertInertia(fn ($page) => $page->where('snippets', [])); +}); + +it('lists the rate limits as the code sets them, in Rate limits only', function (): void { + $this->get(route('api-docs.show', ApiDocsSection::RateLimits)) + ->assertInertia(fn ($page) => $page + ->has('rateLimits', count(resolve(ApiRateLimitsQuery::class)->get())) + ->where('rateLimits.1', ['what' => 'Signed requests', 'limit' => 120, 'per' => 'minute, per person'])); + + $this->get(route('api-docs.show', ApiDocsSection::Users)) + ->assertInertia(fn ($page) => $page->where('rateLimits', [])); +}); + +it('shows how each client signs a request in Authentication only', function (): void { + $this->get(route('api-docs.show', ApiDocsSection::Authentication)) + ->assertInertia(fn ($page) => $page + ->has('signing', 3) + ->where('signing.1.label', 'Laravel')); + + $this->get(route('api-docs.show', ApiDocsSection::Users)) + ->assertInertia(fn ($page) => $page->where('signing', [])); +}); + +it('lists no endpoints in a guide', function (): void { + $this->get(route('api-docs.show', ApiDocsSection::Authentication)) + ->assertInertia(fn ($page) => $page->where('endpoints', [])); +}); + +it('lists every error code with the status it comes with', function (): void { + $this->get(route('api-docs.show', ApiDocsSection::Errors)) + ->assertInertia(fn ($page) => $page + ->has('errorCodes', count(ApiErrorCode::cases())) + ->where('errorCodes.0', ['code' => 'invalid_signature', 'status' => 401, 'meaning' => ApiErrorCode::InvalidSignature->meaning()]) + ->where('errorCodes.2.code', 'invalid_grant') + ->where('errorCodes.2.status', 400)); + + $this->get(route('api-docs.show', ApiDocsSection::Users)) + ->assertInertia(fn ($page) => $page->where('errorCodes', [])); +}); + +it('says what every error code means, and where it can come from', function (ApiErrorCode $code): void { + expect($code->meaning())->not->toBeEmpty(); +})->with(ApiErrorCode::cases()); + +it('says which errors only come from one place', function (): void { + expect(ApiErrorCode::OwnCommit->meaning())->toBe('You cannot report your own commit.') + ->and(ApiErrorCode::CommitUnavailable->meaning())->toContain('report') + ->and(ApiErrorCode::InvalidGrant->meaning())->toContain('another key'); +}); + +it('answers a section the docs do not have with the not found page', function (): void { + $this->get('/docs/api/webhooks') + ->assertNotFound() + ->assertHeader('Content-Type', 'text/html; charset=UTF-8'); +}); + +it('describes each section to search engines and link previews', function (): void { + $this->get(route('api-docs.show', ApiDocsSection::RateLimits)) + ->assertOk() + ->assertSee('Rate limits - API docs - /dev/null', false) + ->assertSee('', false); +}); + +it('names the reference after the groups of the OpenAPI spec', function (): void { + $tags = array_column(json_decode((string) file_get_contents(resource_path('api/openapi.json')), true)['tags'], 'name'); + + expect(array_map(fn (ApiDocsSection $section): string => $section->title(), ApiDocsSection::reference()))->toBe($tags); +}); diff --git a/tests/Feature/Controllers/ApiDocsSchemaControllerTest.php b/tests/Feature/Controllers/ApiDocsSchemaControllerTest.php new file mode 100644 index 0000000000..2a2297bd9f --- /dev/null +++ b/tests/Feature/Controllers/ApiDocsSchemaControllerTest.php @@ -0,0 +1,31 @@ +getJson(route('api-docs-schema.show', [ApiDocsSection::Commits, 'api-commit.store'])) + ->assertOk() + ->assertJsonStructure(['body' => ['code', 'html'], 'responses' => ['201' => ['code', 'html']]]); + + expect(json_decode($response->json('body.code'), true)['properties'])->toHaveKey('body'); +}); + +it('answers an endpoint the group does not have with not found', function (): void { + $this->getJson(route('api-docs-schema.show', [ApiDocsSection::Users, 'api-commit.store']))->assertNotFound(); + $this->getJson(route('api-docs-schema.show', [ApiDocsSection::Users, 'nothing']))->assertNotFound(); +}); + +it('answers an endpoint no group could have with not found', function (): void { + $this->get('/docs/api/users/schemas/'.str_repeat('a', 300))->assertNotFound(); + $this->get('/docs/api/users/schemas/api user')->assertNotFound(); +}); + +it("lets browsers and caches keep an endpoint's schemas for an hour, the same for everyone", function (): void { + $response = $this->get(route('api-docs-schema.show', [ApiDocsSection::Users, 'api-user.show']))->assertOk(); + + expect($response->headers->get('Cache-Control'))->toContain('public', 'max-age=3600') + ->and($response->headers->get('ETag'))->not->toBeNull() + ->and($response->headers->getCookies())->toBe([]); +}); diff --git a/tests/Feature/OpenApiSpecTest.php b/tests/Feature/OpenApiSpecTest.php new file mode 100644 index 0000000000..38bd1f345e --- /dev/null +++ b/tests/Feature/OpenApiSpecTest.php @@ -0,0 +1,184 @@ + + */ +function freshOpenApiSpec(): array +{ + static $spec = null; + + if ($spec === null) { + $path = tempnam(sys_get_temp_dir(), 'openapi'); + Artisan::call('scramble:export', ['--path' => $path]); + $spec = json_decode((string) file_get_contents($path), true, flags: JSON_THROW_ON_ERROR); + File::delete($path); + } + + return $spec; +} + +/** + * @return array + */ +function openApiOperation(string $method, string $path): array +{ + return freshOpenApiSpec()['paths'][$path][$method]; +} + +it('commits the spec the code describes', function (): void { + $committed = json_decode((string) file_get_contents(resource_path('api/openapi.json')), true, flags: JSON_THROW_ON_ERROR); + + expect($committed)->toBe(freshOpenApiSpec(), 'The API changed: migrate your database, run `composer generate:openapi` and commit resources/api/openapi.json.'); +}); + +it('exports the same spec whatever the app is called and whichever language it speaks', function (): void { + config(['app.name' => 'dev-null (local)']); + Number::useLocale('fr'); + $path = tempnam(sys_get_temp_dir(), 'openapi'); + + Artisan::call('scramble:export', ['--path' => $path]); + $spec = json_decode((string) file_get_contents($path), true, flags: JSON_THROW_ON_ERROR); + File::delete($path); + Number::useLocale('en'); + + expect($spec['info']['title'])->toBe('/dev/null') + ->and($spec['components']['schemas']['CreateApiCommitRequest']['properties']['body']['description'])->toStartWith('At most 4,000 characters'); +}); + +it('describes the production API', function (): void { + expect(freshOpenApiSpec()['servers'])->toBe([['url' => 'https://dev-null.sh/api/v1', 'description' => 'Production']]); +}); + +it('groups the endpoints as the docs list them', function (): void { + $spec = freshOpenApiSpec(); + $tags = collect($spec['paths'])->flatMap(fn (array $item): array => collect($item)->pluck('tags')->flatten()->all())->unique()->values(); + + expect(array_column($spec['tags'], 'name'))->toBe(['Commits', 'Headlines', 'Issues', 'Me', 'Notifications', 'Organizations', 'Remotes', 'Scheduled commits', 'Search', 'Users']) + ->and($tags->sort()->values()->all())->toBe(collect(array_column($spec['tags'], 'name'))->sort()->values()->all()) + ->and(openApiOperation('get', '/log/{log}')['tags'])->toBe(['Me']) + ->and(openApiOperation('get', '/starred')['tags'])->toBe(['Me']) + ->and(openApiOperation('get', '/scheduled-commits')['tags'])->toBe(['Scheduled commits']) + ->and(openApiOperation('get', '/headlines')['tags'])->toBe(['Headlines']) + ->and(openApiOperation('post', '/issues')['tags'])->toBe(['Issues']); +}); + +it('leaves out what only the apps use to work', function (): void { + expect(array_keys(freshOpenApiSpec()['paths'])) + ->not->toContain('/apps/mac') + ->not->toContain('/devices') + ->not->toContain('/broadcasting/auth') + ->not->toContain('/me/web-session') + ->not->toContain('/remotes/images/{messageImage}') + ->not->toContain('/remotes/voices/{messageVoice}') + ->not->toContain('/openapi.json'); +}); + +it('names path parameters after what the route reads', function (): void { + $paths = array_keys(freshOpenApiSpec()['paths']); + + expect($paths)->toContain('/users/{handle}', '/users/{handle}/follow', '/remotes/@{handle}/messages', '/remotes/orgs/{org}/members/{handle}', '/commits/{commit}') + ->and(collect(openApiOperation('get', '/users/{handle}')['parameters'])->where('in', 'path')->pluck('name')->all())->toBe(['handle']) + ->and(collect(openApiOperation('put', '/remotes/orgs/{org}/members/{handle}')['parameters'])->where('in', 'path')->pluck('name')->all())->toBe(['org', 'handle']); +}); + +it('describes a parameter a route reads by handle as the handle it is', function (): void { + $handles = collect(freshOpenApiSpec()['paths']) + ->flatMap(fn (array $item): array => collect($item)->flatMap(fn (array $operation): array => $operation['parameters'] ?? [])->all()) + ->where('in', 'path') + ->where('name', 'handle'); + + expect($handles)->not->toBeEmpty() + ->and($handles->pluck('schema')->unique()->values()->all())->toBe([['type' => 'string']]) + ->and(collect(openApiOperation('post', '/users/{handle}/follow')['parameters'])->firstWhere('name', 'handle')['description'])->toBe("The user's handle") + ->and(collect(openApiOperation('put', '/remotes/orgs/{org}/members/{handle}')['parameters'])->firstWhere('name', 'handle')['description'])->toBe("The member's handle"); +}); + +it('says which endpoints need a signed request', function (): void { + $spec = freshOpenApiSpec(); + + expect($spec['components']['securitySchemes']['devnullSignature'])->toMatchArray(['type' => 'apiKey', 'in' => 'header', 'name' => 'X-SSH-Signature']) + ->and(openApiOperation('get', '/me')['security'])->toBe([['devnullSignature' => []]]) + ->and(openApiOperation('post', '/commits')['security'])->toBe([['devnullSignature' => []]]) + ->and(openApiOperation('get', '/users/{handle}')['security'])->toBe([[], ['devnullSignature' => []]]) + ->and(openApiOperation('get', '/commits/{commit}')['security'])->toBe([[], ['devnullSignature' => []]]); +}); + +it('answers a bad signature with its error code', function (): void { + expect(openApiOperation('get', '/me')['responses']['401']['content']['application/json']['schema'])->toBe(['$ref' => '#/components/schemas/ApiError']) + ->and(openApiOperation('get', '/me')['responses']['401']['description'])->toBe('The signature is missing, stale or wrong, or the key that made it is not an approved device.') + ->and(openApiOperation('get', '/users/{handle}')['responses']['401']['description'])->toBe('The signature is stale or wrong, or the key that made it is not an approved device. Without one, the request reads as a guest.'); +}); + +it('answers too many requests with a message, and a code only a signed request gets', function (): void { + $error = freshOpenApiSpec()['components']['schemas']['RateLimitError']; + + expect(openApiOperation('get', '/users/{handle}')['responses']['429']['content']['application/json']['schema'])->toBe(['$ref' => '#/components/schemas/RateLimitError']) + ->and(openApiOperation('post', '/commits')['responses'])->toHaveKey('429') + ->and($error['required'])->toBe(['message']) + ->and($error['properties']['code']['enum'])->toBe(['rate_limited']) + ->and($error['properties']['code']['description'])->toBe('Only a signed request gets it, and never from the pings and commit search limits.'); +}); + +it('describes an author as the user or the organization it is', function (): void { + $variants = freshOpenApiSpec()['components']['schemas']['ProfileResource']['anyOf']; + + expect($variants)->toHaveCount(2) + ->and(array_keys($variants[0]['properties']))->toContain('type', 'id', 'handle', 'name', 'avatar_url', 'html_url') + ->and(array_keys($variants[1]['properties']))->toContain('type', 'id', 'handle', 'name', 'avatar_url', 'html_url'); +}); + +it('describes what resources build with the services they resolve', function (): void { + $signed = freshOpenApiSpec()['components']['schemas']['CommitResource']['anyOf'][0]['properties']; + + expect($signed['mentions']['items']['properties'])->toHaveKeys(['handle', 'offset', 'length', 'kind']) + ->and($signed)->toHaveKeys(['body_segments', 'preview_segments']) + ->and($signed['id'])->toBe(['type' => 'string']); +}); + +it('says how long a commit may be, as links count', function (): void { + $schemas = freshOpenApiSpec()['components']['schemas']; + + expect($schemas['CreateApiCommitRequest']['properties']['body']['description'])->toBe('At most 4,000 characters, where a link outside code counts as 23 at most. Each link must be 2,048 characters at most.') + ->and($schemas['CreateApiScheduledCommitRequest']['properties']['body']['description'])->toBe('At most 4,000 characters, where a link outside code counts as 23 at most. Each link must be 2,048 characters at most.'); +}); + +it('takes a commit as JSON, or as a signed upload of that JSON with its images', function (string $path, string $schema): void { + $body = openApiOperation('post', $path)['requestBody']['content']; + $upload = $body['multipart/form-data']['schema']; + + expect(array_keys($body))->toBe(['application/json', 'multipart/form-data']) + ->and($body['application/json']['schema'])->toBe(['$ref' => "#/components/schemas/{$schema}"]) + ->and(freshOpenApiSpec()['components']['schemas'][$schema]['properties'])->not->toHaveKey('images') + ->and(array_keys($upload['properties']))->toBe(['payload', 'images']) + ->and($upload['required'])->toBe(['payload', 'images']) + ->and($upload['properties']['payload'])->toMatchArray(['type' => 'string', 'format' => 'binary', 'contentMediaType' => 'application/json']) + ->and($upload['properties']['images']['items'])->toMatchArray(['type' => 'string', 'format' => 'binary']); +})->with([ + 'a commit' => ['/commits', 'CreateApiCommitRequest'], + 'a scheduled commit' => ['/scheduled-commits', 'CreateApiScheduledCommitRequest'], + 'a report' => ['/commits/{commit}/reports', 'CreateApiCommitReportRequest'], +]); + +it('takes a poll only when a commit has one, then with its options and duration', function (string $schema): void { + $request = freshOpenApiSpec()['components']['schemas'][$schema]; + + expect($request['required'])->toContain('body')->not->toContain('poll') + ->and($request['properties']['poll']['type'])->toBe(['object', 'null']) + ->and($request['properties']['poll']['required'])->toBe(['options', 'duration']); +})->with(['CreateApiCommitRequest', 'CreateApiScheduledCommitRequest']); + +it('lists every error code the API answers with', function (): void { + $error = freshOpenApiSpec()['components']['schemas']['ApiError']; + + expect($error['required'])->toBe(['message', 'code']) + ->and($error['properties']['code']['enum'])->toBe(array_column(ApiErrorCode::cases(), 'value')); +}); diff --git a/tests/Feature/Queries/ApiDocsQueryTest.php b/tests/Feature/Queries/ApiDocsQueryTest.php new file mode 100644 index 0000000000..5e807ad9df --- /dev/null +++ b/tests/Feature/Queries/ApiDocsQueryTest.php @@ -0,0 +1,261 @@ + $spec + */ +function apiDocsQueryOver(array $spec): ApiDocsQuery +{ + $path = (string) tempnam(sys_get_temp_dir(), 'openapi'); + File::put($path, (string) json_encode($spec)); + + return new ApiDocsQuery(resolve(ApiExamples::class), resolve(Highlighter::class), $path); +} + +it('shows how to call each endpoint', function (): void { + $examples = apiDocsFixtureQuery()->get(ApiDocsSection::Commits)[0]['examples']; + + expect(array_column($examples, 'label'))->toBe(['curl', 'Laravel', 'fetch']) + ->and($examples[0]['code'])->toStartWith('body=\'{"body":"Hello from the API!"}\'') + ->and($examples[0]['code'])->toContain("devnull_sign POST '/api/v1/commits' \"\$body\""); +}); + +it('lists the endpoints of a group, as the spec orders them', function (): void { + $endpoints = apiDocsFixtureQuery()->get(ApiDocsSection::Commits); + + expect(array_column($endpoints, 'id'))->toBe(['api-commit.store', 'api-commit.show']) + ->and($endpoints[0])->toMatchArray([ + 'method' => 'POST', + 'path' => '/commits', + 'summary' => 'Commit, reply or quote', + 'description' => 'Pending review unless the user is an admin.', + 'signature' => 'required', + ]) + ->and(apiDocsFixtureQuery()->get(ApiDocsSection::Users)[0])->toMatchArray([ + 'path' => '/users/{handle}', + 'description' => null, + 'signature' => 'optional', + ]); +}); + +it('describes path and query parameters', function (): void { + expect(apiDocsFixtureQuery()->get(ApiDocsSection::Commits)[1]['parameters'])->toBe([ + ['in' => 'path', 'name' => 'commit', 'type' => 'uuid', 'required' => true, 'description' => null, 'enum' => null, 'children' => []], + ['in' => 'query', 'name' => 'replies', 'type' => 'integer', 'required' => false, 'description' => 'Replies instead.', 'enum' => [0, 1], 'children' => []], + ]); +}); + +it('never says a path parameter may be null', function (): void { + expect(apiDocsFixtureQuery()->get(ApiDocsSection::Users)[0]['parameters'][0])->toMatchArray(['name' => 'handle', 'type' => 'string']); +}); + +it('describes the body a request takes, with what each field must be', function (): void { + $body = apiDocsFixtureQuery()->get(ApiDocsSection::Commits)[0]['body']; + + expect($body['mediaType'])->toBe('multipart/form-data') + ->and($body['fields'][0])->toMatchArray(['name' => 'body', 'type' => 'string', 'required' => true, 'description' => 'At most 4,000 characters.']) + ->and($body['fields'][1])->toMatchArray(['name' => 'images', 'type' => 'array of binary | null', 'required' => false]) + ->and($body['fields'][2])->toMatchArray(['name' => 'image_descriptions', 'type' => 'array of (string | null) | null']) + ->and($body['fields'][3])->toMatchArray(['name' => 'poll', 'type' => 'object', 'required' => false]) + ->and(array_column($body['fields'][3]['children'], 'name'))->toBe(['options', 'duration']) + ->and($body['fields'][3]['children'][1]['required'])->toBeTrue() + ->and(apiDocsFixtureQuery()->get(ApiDocsSection::Users)[0]['body'])->toBeNull(); +}); + +it('describes what a successful answer holds, through the resources it refers to', function (): void { + $response = apiDocsFixtureQuery()->get(ApiDocsSection::Commits)[0]['responses'][0]; + $commit = $response['fields'][0]; + + expect($response)->toMatchArray(['status' => '201', 'description' => '']) + ->and($commit)->toMatchArray(['name' => 'data', 'type' => 'Commit', 'required' => true]) + ->and(array_column($commit['children'], 'name'))->toBe(['id', 'status', 'author', 'parent', 'deleted_at']) + ->and(array_column($commit['children'], 'required'))->toBe([true, false, false, false, false]) + ->and($commit['children'][1])->toMatchArray(['type' => 'CommitStatus', 'enum' => ['pending', 'approved', 'rejected']]) + ->and($commit['children'][2]['type'])->toBe('User | Organization') + ->and(array_column($commit['children'][2]['children'], 'name'))->toBe(['handle', 'bio', 'admins']) + ->and($commit['children'][4]['type'])->toBe('string | null'); +}); + +it('stops at a resource already being described', function (): void { + $parent = apiDocsFixtureQuery()->get(ApiDocsSection::Commits)[0]['responses'][0]['fields'][0]['children'][3]; + + expect($parent)->toMatchArray(['name' => 'parent', 'type' => 'Commit', 'children' => []]); +}); + +it('lists lists of resources as such', function (): void { + expect(apiDocsFixtureQuery()->get(ApiDocsSection::Commits)[1]['responses'][0]['fields'][0]) + ->toMatchArray(['name' => 'data', 'type' => 'array of Commit']) + ->and(apiDocsFixtureQuery()->get(ApiDocsSection::Commits)[1]['responses'][0]['fields'][0]['children'])->not->toBeEmpty(); +}); + +it('leaves the errors every endpoint shares to the Errors guide', function (): void { + $responses = apiDocsFixtureQuery()->get(ApiDocsSection::Users)[0]['responses']; + + expect($responses[1])->toMatchArray(['status' => '401', 'description' => 'The signature is wrong.', 'fields' => []]) + ->and($responses[2])->toMatchArray(['status' => '404', 'description' => 'Not found', 'fields' => []]); +}); + +it('details an error only this endpoint answers with', function (): void { + expect(apiDocsFixtureQuery()->get(ApiDocsSection::Users)[0]['responses'][3])->toMatchArray([ + 'status' => '409', + 'description' => '', + 'fields' => [ + ['name' => 'message', 'type' => 'string', 'required' => true, 'description' => null, 'enum' => ['Unable to claim this organization.'], 'children' => []], + ], + ]); +}); + +it('reads the spec once, until it changes, keeping one copy of each group', function (): void { + $path = (string) tempnam(sys_get_temp_dir(), 'openapi'); + File::copy(base_path('tests/Fixtures/openapi/spec.json'), $path); + + $first = new ApiDocsQuery(resolve(ApiExamples::class), resolve(Highlighter::class), $path)->get(ApiDocsSection::Users); + File::partialMock()->shouldReceive('get')->never(); + $again = new ApiDocsQuery(resolve(ApiExamples::class), resolve(Highlighter::class), $path)->get(ApiDocsSection::Users); + File::swap(new Filesystem); + + file_put_contents($path, str_replace('A profile as it shows on the web', 'Changed', (string) file_get_contents($path))); + $changed = new ApiDocsQuery(resolve(ApiExamples::class), resolve(Highlighter::class), $path)->get(ApiDocsSection::Users); + + expect($first[0]['summary'])->toBe('A profile as it shows on the web') + ->and($again)->toBe($first) + ->and($changed[0]['summary'])->toBe('Changed') + ->and(Cache::get('api-docs:users')['data'])->toBe($changed); + + File::delete($path); +}); + +it('reads the index from the cache, as the groups are', function (): void { + $index = apiDocsFixtureQuery()->index(); + File::partialMock()->shouldReceive('get')->never(); + + expect(apiDocsFixtureQuery()->index())->toBe($index); +}); + +it('lists an endpoint whose items are its own kind without describing it forever', function (): void { + $fields = apiDocsQueryOver([ + 'paths' => ['/trees' => ['get' => ['operationId' => 'api-tree.index', 'tags' => ['Users'], 'responses' => [ + '200' => ['description' => '', 'content' => ['application/json' => ['schema' => ['$ref' => '#/components/schemas/Forest']]]], + ]]]], + 'components' => ['schemas' => ['Forest' => ['type' => 'array', 'items' => ['$ref' => '#/components/schemas/Forest']]]], + ])->get(ApiDocsSection::Users)[0]['responses'][0]['fields']; + + expect($fields)->toBe([]); +}); + +it('names an endpoint without an operation ID so its URL can carry it, and finds its schemas by that name', function (): void { + $query = apiDocsQueryOver([ + 'paths' => ['/users/{handle}/follow' => ['post' => ['tags' => ['Users'], 'responses' => [ + '200' => ['description' => '', 'content' => ['application/json' => ['schema' => ['type' => 'object', 'properties' => ['following' => ['type' => 'boolean']]]]]], + ]]]], + ]); + + expect($query->get(ApiDocsSection::Users)[0]['id'])->toBe('post-users-handle-follow') + ->and(array_keys($query->schemas(ApiDocsSection::Users, 'post-users-handle-follow')['responses']))->toBe([200]); +}); + +it('refuses two endpoints the docs would name alike', function (): void { + apiDocsQueryOver([ + 'paths' => [ + '/users/{handle}/follow' => ['post' => ['tags' => ['Users'], 'responses' => []]], + '/users/{handle}/follows' => ['post' => ['operationId' => 'post-users-handle-follow', 'tags' => ['Users'], 'responses' => []]], + ], + ])->get(ApiDocsSection::Users); +})->throws(LogicException::class, 'Two endpoints of the API docs would both be named post-users-handle-follow.'); + +it('refuses two endpoints whose anchors on the page would be alike', function (): void { + apiDocsQueryOver([ + 'paths' => [ + '/commits/{commit}' => ['get' => ['operationId' => 'api.commit.show', 'tags' => ['Users'], 'responses' => []]], + '/commits/{commit}/again' => ['get' => ['operationId' => 'api-commit-show', 'tags' => ['Users'], 'responses' => []]], + ], + ])->get(ApiDocsSection::Users); +})->throws(LogicException::class, 'Two endpoints of the API docs would both be named api-commit-show.'); + +it('keeps an empty schema an object, and an empty list a list, in the JSON schema it gives', function (): void { + $code = apiDocsQueryOver([ + 'paths' => ['/calls' => ['post' => ['operationId' => 'api-call.store', 'tags' => ['Users'], 'responses' => [ + '200' => ['description' => '', 'content' => ['application/json' => ['schema' => [ + 'type' => 'object', + 'additionalProperties' => new stdClass, + 'properties' => ['meta' => new stdClass, 'tags' => ['type' => 'array', 'items' => new stdClass]], + 'anyOf' => [new stdClass], + 'required' => [], + ]]]], + ]]]], + ])->schemas(ApiDocsSection::Users, 'api-call.store')['responses']['200']['code']; + + expect(json_decode($code))->toEqual((object) [ + 'type' => 'object', + 'additionalProperties' => new stdClass, + 'properties' => (object) ['meta' => new stdClass, 'tags' => (object) ['type' => 'array', 'items' => new stdClass]], + 'anyOf' => [new stdClass], + 'required' => [], + ]); +}); + +it('says an endpoint the spec asks no signature of is public', function (): void { + expect(apiDocsQueryOver([ + 'paths' => ['/status' => ['get' => ['operationId' => 'api-status.show', 'tags' => ['Users'], 'responses' => []]]], + ])->get(ApiDocsSection::Users)[0]['signature'])->toBe('optional'); +}); + +it('indexes every endpoint of the reference, for searching it, its groups in the sidebar order', function (): void { + expect(apiDocsFixtureQuery()->index())->toBe([ + ['id' => 'api-commit.store', 'method' => 'POST', 'path' => '/commits', 'summary' => 'Commit, reply or quote', 'section' => 'commits'], + ['id' => 'api-commit.show', 'method' => 'GET', 'path' => '/commits/{commit}', 'summary' => 'One commit', 'section' => 'commits'], + ['id' => 'api-user.show', 'method' => 'GET', 'path' => '/users/{handle}', 'summary' => 'A profile as it shows on the web', 'section' => 'users'], + ]); +}); + +it('gives the JSON schema of the body a request takes, with what it refers to', function (): void { + $schema = apiDocsFixtureQuery()->schemas(ApiDocsSection::Commits, 'api-commit.store')['body']; + $json = json_decode($schema['code'], true); + + expect($json['properties']['body'])->toBe(['type' => 'string', 'maxLength' => 40000, 'description' => 'At most 4,000 characters.']) + ->and($json['required'])->toBe(['body']) + ->and($schema['code'])->toStartWith("{\n \"type\": \"object\",") + ->and($schema['html'])->toContain(' + +import assert from 'node:assert/strict'; +import { act, createRef, useImperativeHandle, useState } from 'react'; +import { createRoot } from 'react-dom/client'; +import { renderToString } from 'react-dom/server'; +import { afterEach, test, vi } from 'vite-plus/test'; +import { createChoice } from '../../resources/js/components/api-docs/choice'; +import { + Endpoint, + EndpointDetails, + EndpointPath, + MethodChip, + SignatureChip, + endpointAnchor, + isSharedError, + revealEndpoint, + useEndpointOpen, +} from '../../resources/js/components/api-docs/endpoint'; +import { + activeExample, + chooseExample, + useChosenExample, +} from '../../resources/js/components/api-docs/example-choice'; +import { + ExampleTabs, + moveToExample, + tabKeyTarget, +} from '../../resources/js/components/api-docs/example-tabs'; +import { + FieldTable, + SpecText, +} from '../../resources/js/components/api-docs/field-table'; +import type { ApiDocsEndpoint } from '../../resources/js/types'; + +afterEach(() => { + vi.unstubAllGlobals(); +}); + +const endpoint: ApiDocsEndpoint = { + id: 'api-user-follow.store', + method: 'POST', + path: '/users/{handle}/follow', + summary: 'Follow them', + description: null, + signature: 'required', + parameters: [], + body: null, + responses: [], + examples: [], +}; + +test('shows the client picked last on every endpoint that has it', () => { + const { container, storage } = browser(''); + const chosen = createRef<{ label: string | null }>(); + + function Probe() { + const label = useChosenExample(); + useImperativeHandle(chosen, () => ({ label })); + + return null; + } + + const root = createRoot(container); + act(() => root.render()); + const label = () => chosen.current?.label ?? null; + + const labels = ['curl', 'Laravel', 'fetch']; + + assert.equal(activeExample(labels, label()), 0); + + act(() => chooseExample('Laravel')); + + assert.equal(label(), 'Laravel'); + assert.equal(storage.get('api-docs:example'), 'Laravel'); + assert.equal(activeExample(labels, label()), 1); + assert.equal(activeExample(['curl', 'fetch'], label()), 0); + + act(() => root.unmount()); + vi.unstubAllGlobals(); +}); + +function mountChoice(key: string, container: Element) { + const choice = createChoice(key); + const chosen = createRef<{ + value: string | null; + rerender: () => void; + }>(); + + function Probe() { + const value = choice.useChosen(); + const [, setRenders] = useState(0); + useImperativeHandle(chosen, () => ({ + value, + rerender: () => setRenders((renders) => renders + 1), + })); + + return null; + } + + const root = createRoot(container); + act(() => root.render()); + + return { + value: () => chosen.current?.value ?? null, + rerender: () => act(() => chosen.current?.rerender()), + unmount: () => act(() => root.unmount()), + }; +} + +test('reads a choice from the browser once, even when nothing was picked', () => { + const { container } = browser(''); + const getItem = vi.spyOn(window.localStorage, 'getItem'); + const choice = mountChoice('api-docs:test-miss', container); + + choice.rerender(); + choice.rerender(); + + assert.equal(choice.value(), null); + assert.equal(getItem.mock.calls.length, 1); + + choice.unmount(); + vi.unstubAllGlobals(); +}); + +test('forgets a choice when another tab clears the storage', () => { + const { container, storage } = browser(''); + storage.set('api-docs:test-clear', 'schema'); + const choice = mountChoice('api-docs:test-clear', container); + + assert.equal(choice.value(), 'schema'); + + storage.clear(); + act(() => { + window.dispatchEvent( + Object.assign(new Event('storage'), { key: null, newValue: null }), + ); + }); + + assert.equal(choice.value(), null); + + choice.unmount(); + vi.unstubAllGlobals(); +}); + +test('shows the first example, the others a tab away', () => { + const html = renderToString( + …', + }, + { + label: 'fetch', + language: 'javascript', + code: 'fetch()', + html: 'fetch()', + }, + ]} + />, + ); + + assert.match(html, /role="tablist"/); + assert.match(html, /role="tab" aria-selected="true"[^>]*>curl]*tabindex="-1"[^>]*>fetch…<\/span>/); +}); + +test('underlines the active example tab like the page tabs, with an underline that slides', () => { + const html = renderToString( + , + ); + const tabs = html.match(/]*role="tab".*?<\/button>/g) ?? []; + + assert.equal(tabs.length, 2); + assert.ok(tabs.every((tab) => /text-\[15px\]/.test(tab))); + assert.match( + tabs[0] ?? '', + /