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