Merge branch 'issue/2068' into 'develop'
[akkoma] / lib / pleroma / web / api_spec / operations / account_operation.ex
1 # Pleroma: A lightweight social networking server
2 # Copyright © 2017-2020 Pleroma Authors <https://pleroma.social/>
3 # SPDX-License-Identifier: AGPL-3.0-only
4
5 defmodule Pleroma.Web.ApiSpec.AccountOperation do
6 alias OpenApiSpex.Operation
7 alias OpenApiSpex.Reference
8 alias OpenApiSpex.Schema
9 alias Pleroma.Web.ApiSpec.Schemas.Account
10 alias Pleroma.Web.ApiSpec.Schemas.AccountRelationship
11 alias Pleroma.Web.ApiSpec.Schemas.ActorType
12 alias Pleroma.Web.ApiSpec.Schemas.ApiError
13 alias Pleroma.Web.ApiSpec.Schemas.BooleanLike
14 alias Pleroma.Web.ApiSpec.Schemas.List
15 alias Pleroma.Web.ApiSpec.Schemas.Status
16 alias Pleroma.Web.ApiSpec.Schemas.VisibilityScope
17
18 import Pleroma.Web.ApiSpec.Helpers
19
20 @spec open_api_operation(atom) :: Operation.t()
21 def open_api_operation(action) do
22 operation = String.to_existing_atom("#{action}_operation")
23 apply(__MODULE__, operation, [])
24 end
25
26 @spec create_operation() :: Operation.t()
27 def create_operation do
28 %Operation{
29 tags: ["accounts"],
30 summary: "Register an account",
31 description:
32 "Creates a user and account records. Returns an account access token for the app that initiated the request. The app should save this token for later, and should wait for the user to confirm their account by clicking a link in their email inbox.",
33 operationId: "AccountController.create",
34 requestBody: request_body("Parameters", create_request(), required: true),
35 responses: %{
36 200 => Operation.response("Account", "application/json", create_response()),
37 400 => Operation.response("Error", "application/json", ApiError),
38 403 => Operation.response("Error", "application/json", ApiError),
39 429 => Operation.response("Error", "application/json", ApiError)
40 }
41 }
42 end
43
44 def verify_credentials_operation do
45 %Operation{
46 tags: ["accounts"],
47 description: "Test to make sure that the user token works.",
48 summary: "Verify account credentials",
49 operationId: "AccountController.verify_credentials",
50 security: [%{"oAuth" => ["read:accounts"]}],
51 responses: %{
52 200 => Operation.response("Account", "application/json", Account)
53 }
54 }
55 end
56
57 def update_credentials_operation do
58 %Operation{
59 tags: ["accounts"],
60 summary: "Update account credentials",
61 description: "Update the user's display and preferences.",
62 operationId: "AccountController.update_credentials",
63 security: [%{"oAuth" => ["write:accounts"]}],
64 requestBody: request_body("Parameters", update_credentials_request(), required: true),
65 responses: %{
66 200 => Operation.response("Account", "application/json", Account),
67 403 => Operation.response("Error", "application/json", ApiError)
68 }
69 }
70 end
71
72 def relationships_operation do
73 %Operation{
74 tags: ["accounts"],
75 summary: "Check relationships to other accounts",
76 operationId: "AccountController.relationships",
77 description: "Find out whether a given account is followed, blocked, muted, etc.",
78 security: [%{"oAuth" => ["read:follows"]}],
79 parameters: [
80 Operation.parameter(
81 :id,
82 :query,
83 %Schema{
84 oneOf: [%Schema{type: :array, items: %Schema{type: :string}}, %Schema{type: :string}]
85 },
86 "Account IDs",
87 example: "123"
88 )
89 ],
90 responses: %{
91 200 => Operation.response("Account", "application/json", array_of_relationships())
92 }
93 }
94 end
95
96 def show_operation do
97 %Operation{
98 tags: ["accounts"],
99 summary: "Account",
100 operationId: "AccountController.show",
101 description: "View information about a profile.",
102 parameters: [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}],
103 responses: %{
104 200 => Operation.response("Account", "application/json", Account),
105 401 => Operation.response("Error", "application/json", ApiError),
106 404 => Operation.response("Error", "application/json", ApiError)
107 }
108 }
109 end
110
111 def statuses_operation do
112 %Operation{
113 tags: ["accounts"],
114 summary: "Statuses",
115 operationId: "AccountController.statuses",
116 description:
117 "Statuses posted to the given account. Public (for public statuses only), or user token + `read:statuses` (for private statuses the user is authorized to see)",
118 parameters:
119 [
120 %Reference{"$ref": "#/components/parameters/accountIdOrNickname"},
121 Operation.parameter(:pinned, :query, BooleanLike, "Include only pinned statuses"),
122 Operation.parameter(:tagged, :query, :string, "With tag"),
123 Operation.parameter(
124 :only_media,
125 :query,
126 BooleanLike,
127 "Include only statuses with media attached"
128 ),
129 Operation.parameter(
130 :with_muted,
131 :query,
132 BooleanLike,
133 "Include statuses from muted acccounts."
134 ),
135 Operation.parameter(:exclude_reblogs, :query, BooleanLike, "Exclude reblogs"),
136 Operation.parameter(:exclude_replies, :query, BooleanLike, "Exclude replies"),
137 Operation.parameter(
138 :exclude_visibilities,
139 :query,
140 %Schema{type: :array, items: VisibilityScope},
141 "Exclude visibilities"
142 )
143 ] ++ pagination_params(),
144 responses: %{
145 200 => Operation.response("Statuses", "application/json", array_of_statuses()),
146 401 => Operation.response("Error", "application/json", ApiError),
147 404 => Operation.response("Error", "application/json", ApiError)
148 }
149 }
150 end
151
152 def followers_operation do
153 %Operation{
154 tags: ["accounts"],
155 summary: "Followers",
156 operationId: "AccountController.followers",
157 security: [%{"oAuth" => ["read:accounts"]}],
158 description:
159 "Accounts which follow the given account, if network is not hidden by the account owner.",
160 parameters: [
161 %Reference{"$ref": "#/components/parameters/accountIdOrNickname"},
162 Operation.parameter(:id, :query, :string, "ID of the resource owner"),
163 with_relationships_param() | pagination_params()
164 ],
165 responses: %{
166 200 => Operation.response("Accounts", "application/json", array_of_accounts())
167 }
168 }
169 end
170
171 def following_operation do
172 %Operation{
173 tags: ["accounts"],
174 summary: "Following",
175 operationId: "AccountController.following",
176 security: [%{"oAuth" => ["read:accounts"]}],
177 description:
178 "Accounts which the given account is following, if network is not hidden by the account owner.",
179 parameters: [
180 %Reference{"$ref": "#/components/parameters/accountIdOrNickname"},
181 Operation.parameter(:id, :query, :string, "ID of the resource owner"),
182 with_relationships_param() | pagination_params()
183 ],
184 responses: %{200 => Operation.response("Accounts", "application/json", array_of_accounts())}
185 }
186 end
187
188 def lists_operation do
189 %Operation{
190 tags: ["accounts"],
191 summary: "Lists containing this account",
192 operationId: "AccountController.lists",
193 security: [%{"oAuth" => ["read:lists"]}],
194 description: "User lists that you have added this account to.",
195 parameters: [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}],
196 responses: %{200 => Operation.response("Lists", "application/json", array_of_lists())}
197 }
198 end
199
200 def follow_operation do
201 %Operation{
202 tags: ["accounts"],
203 summary: "Follow",
204 operationId: "AccountController.follow",
205 security: [%{"oAuth" => ["follow", "write:follows"]}],
206 description: "Follow the given account",
207 parameters: [
208 %Reference{"$ref": "#/components/parameters/accountIdOrNickname"}
209 ],
210 requestBody:
211 request_body(
212 "Parameters",
213 %Schema{
214 type: :object,
215 properties: %{
216 reblogs: %Schema{
217 type: :boolean,
218 description: "Receive this account's reblogs in home timeline? Defaults to true.",
219 default: true
220 }
221 }
222 },
223 required: false
224 ),
225 responses: %{
226 200 => Operation.response("Relationship", "application/json", AccountRelationship),
227 400 => Operation.response("Error", "application/json", ApiError),
228 404 => Operation.response("Error", "application/json", ApiError)
229 }
230 }
231 end
232
233 def unfollow_operation do
234 %Operation{
235 tags: ["accounts"],
236 summary: "Unfollow",
237 operationId: "AccountController.unfollow",
238 security: [%{"oAuth" => ["follow", "write:follows"]}],
239 description: "Unfollow the given account",
240 parameters: [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}],
241 responses: %{
242 200 => Operation.response("Relationship", "application/json", AccountRelationship),
243 400 => Operation.response("Error", "application/json", ApiError),
244 404 => Operation.response("Error", "application/json", ApiError)
245 }
246 }
247 end
248
249 def mute_operation do
250 %Operation{
251 tags: ["accounts"],
252 summary: "Mute",
253 operationId: "AccountController.mute",
254 security: [%{"oAuth" => ["follow", "write:mutes"]}],
255 requestBody: request_body("Parameters", mute_request()),
256 description:
257 "Mute the given account. Clients should filter statuses and notifications from this account, if received (e.g. due to a boost in the Home timeline).",
258 parameters: [
259 %Reference{"$ref": "#/components/parameters/accountIdOrNickname"},
260 Operation.parameter(
261 :notifications,
262 :query,
263 %Schema{allOf: [BooleanLike], default: true},
264 "Mute notifications in addition to statuses? Defaults to `true`."
265 )
266 ],
267 responses: %{
268 200 => Operation.response("Relationship", "application/json", AccountRelationship)
269 }
270 }
271 end
272
273 def unmute_operation do
274 %Operation{
275 tags: ["accounts"],
276 summary: "Unmute",
277 operationId: "AccountController.unmute",
278 security: [%{"oAuth" => ["follow", "write:mutes"]}],
279 description: "Unmute the given account.",
280 parameters: [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}],
281 responses: %{
282 200 => Operation.response("Relationship", "application/json", AccountRelationship)
283 }
284 }
285 end
286
287 def block_operation do
288 %Operation{
289 tags: ["accounts"],
290 summary: "Block",
291 operationId: "AccountController.block",
292 security: [%{"oAuth" => ["follow", "write:blocks"]}],
293 description:
294 "Block the given account. Clients should filter statuses from this account if received (e.g. due to a boost in the Home timeline)",
295 parameters: [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}],
296 responses: %{
297 200 => Operation.response("Relationship", "application/json", AccountRelationship)
298 }
299 }
300 end
301
302 def unblock_operation do
303 %Operation{
304 tags: ["accounts"],
305 summary: "Unblock",
306 operationId: "AccountController.unblock",
307 security: [%{"oAuth" => ["follow", "write:blocks"]}],
308 description: "Unblock the given account.",
309 parameters: [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}],
310 responses: %{
311 200 => Operation.response("Relationship", "application/json", AccountRelationship)
312 }
313 }
314 end
315
316 def follow_by_uri_operation do
317 %Operation{
318 tags: ["accounts"],
319 summary: "Follow by URI",
320 operationId: "AccountController.follows",
321 security: [%{"oAuth" => ["follow", "write:follows"]}],
322 requestBody: request_body("Parameters", follow_by_uri_request(), required: true),
323 responses: %{
324 200 => Operation.response("Account", "application/json", AccountRelationship),
325 400 => Operation.response("Error", "application/json", ApiError),
326 404 => Operation.response("Error", "application/json", ApiError)
327 }
328 }
329 end
330
331 def mutes_operation do
332 %Operation{
333 tags: ["accounts"],
334 summary: "Muted accounts",
335 operationId: "AccountController.mutes",
336 description: "Accounts the user has muted.",
337 security: [%{"oAuth" => ["follow", "read:mutes"]}],
338 responses: %{
339 200 => Operation.response("Accounts", "application/json", array_of_accounts())
340 }
341 }
342 end
343
344 def blocks_operation do
345 %Operation{
346 tags: ["accounts"],
347 summary: "Blocked users",
348 operationId: "AccountController.blocks",
349 description: "View your blocks. See also accounts/:id/{block,unblock}",
350 security: [%{"oAuth" => ["read:blocks"]}],
351 responses: %{
352 200 => Operation.response("Accounts", "application/json", array_of_accounts())
353 }
354 }
355 end
356
357 def endorsements_operation do
358 %Operation{
359 tags: ["accounts"],
360 summary: "Endorsements",
361 operationId: "AccountController.endorsements",
362 description: "Not implemented",
363 security: [%{"oAuth" => ["read:accounts"]}],
364 responses: %{
365 200 => empty_array_response()
366 }
367 }
368 end
369
370 def identity_proofs_operation do
371 %Operation{
372 tags: ["accounts"],
373 summary: "Identity proofs",
374 operationId: "AccountController.identity_proofs",
375 description: "Not implemented",
376 responses: %{
377 200 => empty_array_response()
378 }
379 }
380 end
381
382 defp create_request do
383 %Schema{
384 title: "AccountCreateRequest",
385 description: "POST body for creating an account",
386 type: :object,
387 required: [:username, :password, :agreement],
388 properties: %{
389 reason: %Schema{
390 type: :string,
391 nullable: true,
392 description:
393 "Text that will be reviewed by moderators if registrations require manual approval"
394 },
395 username: %Schema{type: :string, description: "The desired username for the account"},
396 email: %Schema{
397 type: :string,
398 nullable: true,
399 description:
400 "The email address to be used for login. Required when `account_activation_required` is enabled.",
401 format: :email
402 },
403 password: %Schema{
404 type: :string,
405 description: "The password to be used for login",
406 format: :password
407 },
408 agreement: %Schema{
409 allOf: [BooleanLike],
410 description:
411 "Whether the user agrees to the local rules, terms, and policies. These should be presented to the user in order to allow them to consent before setting this parameter to TRUE."
412 },
413 locale: %Schema{
414 type: :string,
415 nullable: true,
416 description: "The language of the confirmation email that will be sent"
417 },
418 # Pleroma-specific properties:
419 fullname: %Schema{type: :string, nullable: true, description: "Full name"},
420 bio: %Schema{type: :string, description: "Bio", nullable: true, default: ""},
421 captcha_solution: %Schema{
422 type: :string,
423 nullable: true,
424 description: "Provider-specific captcha solution"
425 },
426 captcha_token: %Schema{
427 type: :string,
428 nullable: true,
429 description: "Provider-specific captcha token"
430 },
431 captcha_answer_data: %Schema{
432 type: :string,
433 nullable: true,
434 description: "Provider-specific captcha data"
435 },
436 token: %Schema{
437 type: :string,
438 nullable: true,
439 description: "Invite token required when the registrations aren't public"
440 }
441 },
442 example: %{
443 "username" => "cofe",
444 "email" => "cofe@example.com",
445 "password" => "secret",
446 "agreement" => "true",
447 "bio" => "☕️"
448 }
449 }
450 end
451
452 # Note: this is a token response (if login succeeds!), but there's no oauth operation file yet.
453 defp create_response do
454 %Schema{
455 title: "AccountCreateResponse",
456 description: "Response schema for an account",
457 type: :object,
458 properties: %{
459 # The response when auto-login on create succeeds (token is issued):
460 token_type: %Schema{type: :string},
461 access_token: %Schema{type: :string},
462 refresh_token: %Schema{type: :string},
463 scope: %Schema{type: :string},
464 created_at: %Schema{type: :integer, format: :"date-time"},
465 me: %Schema{type: :string},
466 expires_in: %Schema{type: :integer},
467 #
468 # The response when registration succeeds but auto-login fails (no token):
469 identifier: %Schema{type: :string},
470 message: %Schema{type: :string}
471 },
472 required: [],
473 # Note: example of successful registration with failed login response:
474 # example: %{
475 # "identifier" => "missing_confirmed_email",
476 # "message" => "You have been registered. Please check your email for further instructions."
477 # },
478 example: %{
479 "token_type" => "Bearer",
480 "access_token" => "i9hAVVzGld86Pl5JtLtizKoXVvtTlSCJvwaugCxvZzk",
481 "refresh_token" => "i9hAVVzGld86Pl5JtLtizKoXVvtTlSCJvwaugCxvZzz",
482 "created_at" => 1_585_918_714,
483 "expires_in" => 600,
484 "scope" => "read write follow push",
485 "me" => "https://gensokyo.2hu/users/raymoo"
486 }
487 }
488 end
489
490 defp update_credentials_request do
491 %Schema{
492 title: "AccountUpdateCredentialsRequest",
493 description: "POST body for creating an account",
494 type: :object,
495 properties: %{
496 bot: %Schema{
497 allOf: [BooleanLike],
498 nullable: true,
499 description: "Whether the account has a bot flag."
500 },
501 display_name: %Schema{
502 type: :string,
503 nullable: true,
504 description: "The display name to use for the profile."
505 },
506 note: %Schema{type: :string, description: "The account bio."},
507 avatar: %Schema{
508 type: :string,
509 nullable: true,
510 description: "Avatar image encoded using multipart/form-data",
511 format: :binary
512 },
513 header: %Schema{
514 type: :string,
515 nullable: true,
516 description: "Header image encoded using multipart/form-data",
517 format: :binary
518 },
519 locked: %Schema{
520 allOf: [BooleanLike],
521 nullable: true,
522 description: "Whether manual approval of follow requests is required."
523 },
524 accepts_chat_messages: %Schema{
525 allOf: [BooleanLike],
526 nullable: true,
527 description: "Whether the user accepts receiving chat messages."
528 },
529 fields_attributes: %Schema{
530 nullable: true,
531 oneOf: [
532 %Schema{type: :array, items: attribute_field()},
533 %Schema{type: :object, additionalProperties: %Schema{type: attribute_field()}}
534 ]
535 },
536 # NOTE: `source` field is not supported
537 #
538 # source: %Schema{
539 # type: :object,
540 # properties: %{
541 # privacy: %Schema{type: :string},
542 # sensitive: %Schema{type: :boolean},
543 # language: %Schema{type: :string}
544 # }
545 # },
546
547 # Pleroma-specific fields
548 no_rich_text: %Schema{
549 allOf: [BooleanLike],
550 nullable: true,
551 description: "html tags are stripped from all statuses requested from the API"
552 },
553 hide_followers: %Schema{
554 allOf: [BooleanLike],
555 nullable: true,
556 description: "user's followers will be hidden"
557 },
558 hide_follows: %Schema{
559 allOf: [BooleanLike],
560 nullable: true,
561 description: "user's follows will be hidden"
562 },
563 hide_followers_count: %Schema{
564 allOf: [BooleanLike],
565 nullable: true,
566 description: "user's follower count will be hidden"
567 },
568 hide_follows_count: %Schema{
569 allOf: [BooleanLike],
570 nullable: true,
571 description: "user's follow count will be hidden"
572 },
573 hide_favorites: %Schema{
574 allOf: [BooleanLike],
575 nullable: true,
576 description: "user's favorites timeline will be hidden"
577 },
578 show_role: %Schema{
579 allOf: [BooleanLike],
580 nullable: true,
581 description: "user's role (e.g admin, moderator) will be exposed to anyone in the
582 API"
583 },
584 default_scope: VisibilityScope,
585 pleroma_settings_store: %Schema{
586 type: :object,
587 nullable: true,
588 description: "Opaque user settings to be saved on the backend."
589 },
590 skip_thread_containment: %Schema{
591 allOf: [BooleanLike],
592 nullable: true,
593 description: "Skip filtering out broken threads"
594 },
595 allow_following_move: %Schema{
596 allOf: [BooleanLike],
597 nullable: true,
598 description: "Allows automatically follow moved following accounts"
599 },
600 pleroma_background_image: %Schema{
601 type: :string,
602 nullable: true,
603 description: "Sets the background image of the user.",
604 format: :binary
605 },
606 discoverable: %Schema{
607 allOf: [BooleanLike],
608 nullable: true,
609 description:
610 "Discovery of this account in search results and other services is allowed."
611 },
612 actor_type: ActorType
613 },
614 example: %{
615 bot: false,
616 display_name: "cofe",
617 note: "foobar",
618 fields_attributes: [%{name: "foo", value: "bar"}],
619 no_rich_text: false,
620 hide_followers: true,
621 hide_follows: false,
622 hide_followers_count: false,
623 hide_follows_count: false,
624 hide_favorites: false,
625 show_role: false,
626 default_scope: "private",
627 pleroma_settings_store: %{"pleroma-fe" => %{"key" => "val"}},
628 skip_thread_containment: false,
629 allow_following_move: false,
630 discoverable: false,
631 actor_type: "Person"
632 }
633 }
634 end
635
636 def array_of_accounts do
637 %Schema{
638 title: "ArrayOfAccounts",
639 type: :array,
640 items: Account,
641 example: [Account.schema().example]
642 }
643 end
644
645 defp array_of_relationships do
646 %Schema{
647 title: "ArrayOfRelationships",
648 description: "Response schema for account relationships",
649 type: :array,
650 items: AccountRelationship,
651 example: [
652 %{
653 "id" => "1",
654 "following" => true,
655 "showing_reblogs" => true,
656 "followed_by" => true,
657 "blocking" => false,
658 "blocked_by" => true,
659 "muting" => false,
660 "muting_notifications" => false,
661 "requested" => false,
662 "domain_blocking" => false,
663 "subscribing" => false,
664 "endorsed" => true
665 },
666 %{
667 "id" => "2",
668 "following" => true,
669 "showing_reblogs" => true,
670 "followed_by" => true,
671 "blocking" => false,
672 "blocked_by" => true,
673 "muting" => true,
674 "muting_notifications" => false,
675 "requested" => true,
676 "domain_blocking" => false,
677 "subscribing" => false,
678 "endorsed" => false
679 },
680 %{
681 "id" => "3",
682 "following" => true,
683 "showing_reblogs" => true,
684 "followed_by" => true,
685 "blocking" => true,
686 "blocked_by" => false,
687 "muting" => true,
688 "muting_notifications" => false,
689 "requested" => false,
690 "domain_blocking" => true,
691 "subscribing" => true,
692 "endorsed" => false
693 }
694 ]
695 }
696 end
697
698 defp follow_by_uri_request do
699 %Schema{
700 title: "AccountFollowsRequest",
701 description: "POST body for muting an account",
702 type: :object,
703 properties: %{
704 uri: %Schema{type: :string, nullable: true, format: :uri}
705 },
706 required: [:uri]
707 }
708 end
709
710 defp mute_request do
711 %Schema{
712 title: "AccountMuteRequest",
713 description: "POST body for muting an account",
714 type: :object,
715 properties: %{
716 notifications: %Schema{
717 allOf: [BooleanLike],
718 nullable: true,
719 description: "Mute notifications in addition to statuses? Defaults to true.",
720 default: true
721 }
722 },
723 example: %{
724 "notifications" => true
725 }
726 }
727 end
728
729 defp array_of_lists do
730 %Schema{
731 title: "ArrayOfLists",
732 description: "Response schema for lists",
733 type: :array,
734 items: List,
735 example: [
736 %{"id" => "123", "title" => "my list"},
737 %{"id" => "1337", "title" => "anotehr list"}
738 ]
739 }
740 end
741
742 defp array_of_statuses do
743 %Schema{
744 title: "ArrayOfStatuses",
745 type: :array,
746 items: Status
747 }
748 end
749
750 defp attribute_field do
751 %Schema{
752 title: "AccountAttributeField",
753 description: "Request schema for account custom fields",
754 type: :object,
755 properties: %{
756 name: %Schema{type: :string},
757 value: %Schema{type: :string}
758 },
759 required: [:name, :value],
760 example: %{
761 "name" => "Website",
762 "value" => "https://pleroma.com"
763 }
764 }
765 end
766 end