Fix digest mix task on OTP releases
[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_creadentials_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 404 => Operation.response("Error", "application/json", ApiError)
106 }
107 }
108 end
109
110 def statuses_operation do
111 %Operation{
112 tags: ["accounts"],
113 summary: "Statuses",
114 operationId: "AccountController.statuses",
115 description:
116 "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)",
117 parameters:
118 [
119 %Reference{"$ref": "#/components/parameters/accountIdOrNickname"},
120 Operation.parameter(:pinned, :query, BooleanLike, "Include only pinned statuses"),
121 Operation.parameter(:tagged, :query, :string, "With tag"),
122 Operation.parameter(
123 :only_media,
124 :query,
125 BooleanLike,
126 "Include only statuses with media attached"
127 ),
128 Operation.parameter(
129 :with_muted,
130 :query,
131 BooleanLike,
132 "Include statuses from muted acccounts."
133 ),
134 Operation.parameter(:exclude_reblogs, :query, BooleanLike, "Exclude reblogs"),
135 Operation.parameter(:exclude_replies, :query, BooleanLike, "Exclude replies"),
136 Operation.parameter(
137 :exclude_visibilities,
138 :query,
139 %Schema{type: :array, items: VisibilityScope},
140 "Exclude visibilities"
141 )
142 ] ++ pagination_params(),
143 responses: %{
144 200 => Operation.response("Statuses", "application/json", array_of_statuses()),
145 404 => Operation.response("Error", "application/json", ApiError)
146 }
147 }
148 end
149
150 def followers_operation do
151 %Operation{
152 tags: ["accounts"],
153 summary: "Followers",
154 operationId: "AccountController.followers",
155 security: [%{"oAuth" => ["read:accounts"]}],
156 description:
157 "Accounts which follow the given account, if network is not hidden by the account owner.",
158 parameters:
159 [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}] ++ pagination_params(),
160 responses: %{
161 200 => Operation.response("Accounts", "application/json", array_of_accounts())
162 }
163 }
164 end
165
166 def following_operation do
167 %Operation{
168 tags: ["accounts"],
169 summary: "Following",
170 operationId: "AccountController.following",
171 security: [%{"oAuth" => ["read:accounts"]}],
172 description:
173 "Accounts which the given account is following, if network is not hidden by the account owner.",
174 parameters:
175 [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}] ++ pagination_params(),
176 responses: %{200 => Operation.response("Accounts", "application/json", array_of_accounts())}
177 }
178 end
179
180 def lists_operation do
181 %Operation{
182 tags: ["accounts"],
183 summary: "Lists containing this account",
184 operationId: "AccountController.lists",
185 security: [%{"oAuth" => ["read:lists"]}],
186 description: "User lists that you have added this account to.",
187 parameters: [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}],
188 responses: %{200 => Operation.response("Lists", "application/json", array_of_lists())}
189 }
190 end
191
192 def follow_operation do
193 %Operation{
194 tags: ["accounts"],
195 summary: "Follow",
196 operationId: "AccountController.follow",
197 security: [%{"oAuth" => ["follow", "write:follows"]}],
198 description: "Follow the given account",
199 parameters: [
200 %Reference{"$ref": "#/components/parameters/accountIdOrNickname"},
201 Operation.parameter(
202 :reblogs,
203 :query,
204 BooleanLike,
205 "Receive this account's reblogs in home timeline? Defaults to true."
206 )
207 ],
208 responses: %{
209 200 => Operation.response("Relationship", "application/json", AccountRelationship),
210 400 => Operation.response("Error", "application/json", ApiError),
211 404 => Operation.response("Error", "application/json", ApiError)
212 }
213 }
214 end
215
216 def unfollow_operation do
217 %Operation{
218 tags: ["accounts"],
219 summary: "Unfollow",
220 operationId: "AccountController.unfollow",
221 security: [%{"oAuth" => ["follow", "write:follows"]}],
222 description: "Unfollow the given account",
223 parameters: [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}],
224 responses: %{
225 200 => Operation.response("Relationship", "application/json", AccountRelationship),
226 400 => Operation.response("Error", "application/json", ApiError),
227 404 => Operation.response("Error", "application/json", ApiError)
228 }
229 }
230 end
231
232 def mute_operation do
233 %Operation{
234 tags: ["accounts"],
235 summary: "Mute",
236 operationId: "AccountController.mute",
237 security: [%{"oAuth" => ["follow", "write:mutes"]}],
238 requestBody: request_body("Parameters", mute_request()),
239 description:
240 "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).",
241 parameters: [
242 %Reference{"$ref": "#/components/parameters/accountIdOrNickname"},
243 Operation.parameter(
244 :notifications,
245 :query,
246 %Schema{allOf: [BooleanLike], default: true},
247 "Mute notifications in addition to statuses? Defaults to `true`."
248 )
249 ],
250 responses: %{
251 200 => Operation.response("Relationship", "application/json", AccountRelationship)
252 }
253 }
254 end
255
256 def unmute_operation do
257 %Operation{
258 tags: ["accounts"],
259 summary: "Unmute",
260 operationId: "AccountController.unmute",
261 security: [%{"oAuth" => ["follow", "write:mutes"]}],
262 description: "Unmute the given account.",
263 parameters: [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}],
264 responses: %{
265 200 => Operation.response("Relationship", "application/json", AccountRelationship)
266 }
267 }
268 end
269
270 def block_operation do
271 %Operation{
272 tags: ["accounts"],
273 summary: "Block",
274 operationId: "AccountController.block",
275 security: [%{"oAuth" => ["follow", "write:blocks"]}],
276 description:
277 "Block the given account. Clients should filter statuses from this account if received (e.g. due to a boost in the Home timeline)",
278 parameters: [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}],
279 responses: %{
280 200 => Operation.response("Relationship", "application/json", AccountRelationship)
281 }
282 }
283 end
284
285 def unblock_operation do
286 %Operation{
287 tags: ["accounts"],
288 summary: "Unblock",
289 operationId: "AccountController.unblock",
290 security: [%{"oAuth" => ["follow", "write:blocks"]}],
291 description: "Unblock the given account.",
292 parameters: [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}],
293 responses: %{
294 200 => Operation.response("Relationship", "application/json", AccountRelationship)
295 }
296 }
297 end
298
299 def follow_by_uri_operation do
300 %Operation{
301 tags: ["accounts"],
302 summary: "Follow by URI",
303 operationId: "AccountController.follows",
304 security: [%{"oAuth" => ["follow", "write:follows"]}],
305 requestBody: request_body("Parameters", follow_by_uri_request(), required: true),
306 responses: %{
307 200 => Operation.response("Account", "application/json", AccountRelationship),
308 400 => Operation.response("Error", "application/json", ApiError),
309 404 => Operation.response("Error", "application/json", ApiError)
310 }
311 }
312 end
313
314 def mutes_operation do
315 %Operation{
316 tags: ["accounts"],
317 summary: "Muted accounts",
318 operationId: "AccountController.mutes",
319 description: "Accounts the user has muted.",
320 security: [%{"oAuth" => ["follow", "read:mutes"]}],
321 responses: %{
322 200 => Operation.response("Accounts", "application/json", array_of_accounts())
323 }
324 }
325 end
326
327 def blocks_operation do
328 %Operation{
329 tags: ["accounts"],
330 summary: "Blocked users",
331 operationId: "AccountController.blocks",
332 description: "View your blocks. See also accounts/:id/{block,unblock}",
333 security: [%{"oAuth" => ["read:blocks"]}],
334 responses: %{
335 200 => Operation.response("Accounts", "application/json", array_of_accounts())
336 }
337 }
338 end
339
340 def endorsements_operation do
341 %Operation{
342 tags: ["accounts"],
343 summary: "Endorsements",
344 operationId: "AccountController.endorsements",
345 description: "Not implemented",
346 security: [%{"oAuth" => ["read:accounts"]}],
347 responses: %{
348 200 => empty_array_response()
349 }
350 }
351 end
352
353 def identity_proofs_operation do
354 %Operation{
355 tags: ["accounts"],
356 summary: "Identity proofs",
357 operationId: "AccountController.identity_proofs",
358 description: "Not implemented",
359 responses: %{
360 200 => empty_array_response()
361 }
362 }
363 end
364
365 defp create_request do
366 %Schema{
367 title: "AccountCreateRequest",
368 description: "POST body for creating an account",
369 type: :object,
370 properties: %{
371 reason: %Schema{
372 type: :string,
373 description:
374 "Text that will be reviewed by moderators if registrations require manual approval"
375 },
376 username: %Schema{type: :string, description: "The desired username for the account"},
377 email: %Schema{
378 type: :string,
379 description:
380 "The email address to be used for login. Required when `account_activation_required` is enabled.",
381 format: :email
382 },
383 password: %Schema{
384 type: :string,
385 description: "The password to be used for login",
386 format: :password
387 },
388 agreement: %Schema{
389 type: :boolean,
390 description:
391 "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."
392 },
393 locale: %Schema{
394 type: :string,
395 description: "The language of the confirmation email that will be sent"
396 },
397 # Pleroma-specific properties:
398 fullname: %Schema{type: :string, description: "Full name"},
399 bio: %Schema{type: :string, description: "Bio", default: ""},
400 captcha_solution: %Schema{
401 type: :string,
402 description: "Provider-specific captcha solution"
403 },
404 captcha_token: %Schema{type: :string, description: "Provider-specific captcha token"},
405 captcha_answer_data: %Schema{type: :string, description: "Provider-specific captcha data"},
406 token: %Schema{
407 type: :string,
408 description: "Invite token required when the registrations aren't public"
409 }
410 },
411 required: [:username, :password, :agreement],
412 example: %{
413 "username" => "cofe",
414 "email" => "cofe@example.com",
415 "password" => "secret",
416 "agreement" => "true",
417 "bio" => "☕️"
418 }
419 }
420 end
421
422 defp create_response do
423 %Schema{
424 title: "AccountCreateResponse",
425 description: "Response schema for an account",
426 type: :object,
427 properties: %{
428 token_type: %Schema{type: :string},
429 access_token: %Schema{type: :string},
430 scope: %Schema{type: :array, items: %Schema{type: :string}},
431 created_at: %Schema{type: :integer, format: :"date-time"}
432 },
433 example: %{
434 "access_token" => "i9hAVVzGld86Pl5JtLtizKoXVvtTlSCJvwaugCxvZzk",
435 "created_at" => 1_585_918_714,
436 "scope" => ["read", "write", "follow", "push"],
437 "token_type" => "Bearer"
438 }
439 }
440 end
441
442 defp update_creadentials_request do
443 %Schema{
444 title: "AccountUpdateCredentialsRequest",
445 description: "POST body for creating an account",
446 type: :object,
447 properties: %{
448 bot: %Schema{
449 type: :boolean,
450 description: "Whether the account has a bot flag."
451 },
452 display_name: %Schema{
453 type: :string,
454 description: "The display name to use for the profile."
455 },
456 note: %Schema{type: :string, description: "The account bio."},
457 avatar: %Schema{
458 type: :string,
459 description: "Avatar image encoded using multipart/form-data",
460 format: :binary
461 },
462 header: %Schema{
463 type: :string,
464 description: "Header image encoded using multipart/form-data",
465 format: :binary
466 },
467 locked: %Schema{
468 type: :boolean,
469 description: "Whether manual approval of follow requests is required."
470 },
471 fields_attributes: %Schema{
472 oneOf: [
473 %Schema{type: :array, items: attribute_field()},
474 %Schema{type: :object, additionalProperties: %Schema{type: attribute_field()}}
475 ]
476 },
477 # NOTE: `source` field is not supported
478 #
479 # source: %Schema{
480 # type: :object,
481 # properties: %{
482 # privacy: %Schema{type: :string},
483 # sensitive: %Schema{type: :boolean},
484 # language: %Schema{type: :string}
485 # }
486 # },
487
488 # Pleroma-specific fields
489 no_rich_text: %Schema{
490 type: :boolean,
491 description: "html tags are stripped from all statuses requested from the API"
492 },
493 hide_followers: %Schema{type: :boolean, description: "user's followers will be hidden"},
494 hide_follows: %Schema{type: :boolean, description: "user's follows will be hidden"},
495 hide_followers_count: %Schema{
496 type: :boolean,
497 description: "user's follower count will be hidden"
498 },
499 hide_follows_count: %Schema{
500 type: :boolean,
501 description: "user's follow count will be hidden"
502 },
503 hide_favorites: %Schema{
504 type: :boolean,
505 description: "user's favorites timeline will be hidden"
506 },
507 show_role: %Schema{
508 type: :boolean,
509 description: "user's role (e.g admin, moderator) will be exposed to anyone in the
510 API"
511 },
512 default_scope: VisibilityScope,
513 pleroma_settings_store: %Schema{
514 type: :object,
515 description: "Opaque user settings to be saved on the backend."
516 },
517 skip_thread_containment: %Schema{
518 type: :boolean,
519 description: "Skip filtering out broken threads"
520 },
521 allow_following_move: %Schema{
522 type: :boolean,
523 description: "Allows automatically follow moved following accounts"
524 },
525 pleroma_background_image: %Schema{
526 type: :string,
527 description: "Sets the background image of the user.",
528 format: :binary
529 },
530 discoverable: %Schema{
531 type: :boolean,
532 description:
533 "Discovery of this account in search results and other services is allowed."
534 },
535 actor_type: ActorType
536 },
537 example: %{
538 bot: false,
539 display_name: "cofe",
540 note: "foobar",
541 fields_attributes: [%{name: "foo", value: "bar"}],
542 no_rich_text: false,
543 hide_followers: true,
544 hide_follows: false,
545 hide_followers_count: false,
546 hide_follows_count: false,
547 hide_favorites: false,
548 show_role: false,
549 default_scope: "private",
550 pleroma_settings_store: %{"pleroma-fe" => %{"key" => "val"}},
551 skip_thread_containment: false,
552 allow_following_move: false,
553 discoverable: false,
554 actor_type: "Person"
555 }
556 }
557 end
558
559 def array_of_accounts do
560 %Schema{
561 title: "ArrayOfAccounts",
562 type: :array,
563 items: Account,
564 example: [Account.schema().example]
565 }
566 end
567
568 defp array_of_relationships do
569 %Schema{
570 title: "ArrayOfRelationships",
571 description: "Response schema for account relationships",
572 type: :array,
573 items: AccountRelationship,
574 example: [
575 %{
576 "id" => "1",
577 "following" => true,
578 "showing_reblogs" => true,
579 "followed_by" => true,
580 "blocking" => false,
581 "blocked_by" => true,
582 "muting" => false,
583 "muting_notifications" => false,
584 "requested" => false,
585 "domain_blocking" => false,
586 "subscribing" => false,
587 "endorsed" => true
588 },
589 %{
590 "id" => "2",
591 "following" => true,
592 "showing_reblogs" => true,
593 "followed_by" => true,
594 "blocking" => false,
595 "blocked_by" => true,
596 "muting" => true,
597 "muting_notifications" => false,
598 "requested" => true,
599 "domain_blocking" => false,
600 "subscribing" => false,
601 "endorsed" => false
602 },
603 %{
604 "id" => "3",
605 "following" => true,
606 "showing_reblogs" => true,
607 "followed_by" => true,
608 "blocking" => true,
609 "blocked_by" => false,
610 "muting" => true,
611 "muting_notifications" => false,
612 "requested" => false,
613 "domain_blocking" => true,
614 "subscribing" => true,
615 "endorsed" => false
616 }
617 ]
618 }
619 end
620
621 defp follow_by_uri_request do
622 %Schema{
623 title: "AccountFollowsRequest",
624 description: "POST body for muting an account",
625 type: :object,
626 properties: %{
627 uri: %Schema{type: :string, format: :uri}
628 },
629 required: [:uri]
630 }
631 end
632
633 defp mute_request do
634 %Schema{
635 title: "AccountMuteRequest",
636 description: "POST body for muting an account",
637 type: :object,
638 properties: %{
639 notifications: %Schema{
640 type: :boolean,
641 description: "Mute notifications in addition to statuses? Defaults to true.",
642 default: true
643 }
644 },
645 example: %{
646 "notifications" => true
647 }
648 }
649 end
650
651 defp array_of_lists do
652 %Schema{
653 title: "ArrayOfLists",
654 description: "Response schema for lists",
655 type: :array,
656 items: List,
657 example: [
658 %{"id" => "123", "title" => "my list"},
659 %{"id" => "1337", "title" => "anotehr list"}
660 ]
661 }
662 end
663
664 defp array_of_statuses do
665 %Schema{
666 title: "ArrayOfStatuses",
667 type: :array,
668 items: Status
669 }
670 end
671
672 defp attribute_field do
673 %Schema{
674 title: "AccountAttributeField",
675 description: "Request schema for account custom fields",
676 type: :object,
677 properties: %{
678 name: %Schema{type: :string},
679 value: %Schema{type: :string}
680 },
681 required: [:name, :value],
682 example: %{
683 "name" => "Website",
684 "value" => "https://pleroma.com"
685 }
686 }
687 end
688 end