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_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         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_credentials_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         accepts_chat_messages: %Schema{
 496           allOf: [BooleanLike],
 497           nullable: true,
 498           description: "Whether the user accepts receiving chat messages."
 499         },
 500         fields_attributes: %Schema{
 501           nullable: true,
 502           oneOf: [
 503             %Schema{type: :array, items: attribute_field()},
 504             %Schema{type: :object, additionalProperties: %Schema{type: attribute_field()}}
 505           ]
 506         },
 507         # NOTE: `source` field is not supported
 508         #
 509         # source: %Schema{
 510         #   type: :object,
 511         #   properties: %{
 512         #     privacy: %Schema{type: :string},
 513         #     sensitive: %Schema{type: :boolean},
 514         #     language: %Schema{type: :string}
 515         #   }
 516         # },
 517
 518         # Pleroma-specific fields
 519         no_rich_text: %Schema{
 520           allOf: [BooleanLike],
 521           nullable: true,
 522           description: "html tags are stripped from all statuses requested from the API"
 523         },
 524         hide_followers: %Schema{
 525           allOf: [BooleanLike],
 526           nullable: true,
 527           description: "user's followers will be hidden"
 528         },
 529         hide_follows: %Schema{
 530           allOf: [BooleanLike],
 531           nullable: true,
 532           description: "user's follows will be hidden"
 533         },
 534         hide_followers_count: %Schema{
 535           allOf: [BooleanLike],
 536           nullable: true,
 537           description: "user's follower count will be hidden"
 538         },
 539         hide_follows_count: %Schema{
 540           allOf: [BooleanLike],
 541           nullable: true,
 542           description: "user's follow count will be hidden"
 543         },
 544         hide_favorites: %Schema{
 545           allOf: [BooleanLike],
 546           nullable: true,
 547           description: "user's favorites timeline will be hidden"
 548         },
 549         show_role: %Schema{
 550           allOf: [BooleanLike],
 551           nullable: true,
 552           description: "user's role (e.g admin, moderator) will be exposed to anyone in the
 553         API"
 554         },
 555         default_scope: VisibilityScope,
 556         pleroma_settings_store: %Schema{
 557           type: :object,
 558           nullable: true,
 559           description: "Opaque user settings to be saved on the backend."
 560         },
 561         skip_thread_containment: %Schema{
 562           allOf: [BooleanLike],
 563           nullable: true,
 564           description: "Skip filtering out broken threads"
 565         },
 566         allow_following_move: %Schema{
 567           allOf: [BooleanLike],
 568           nullable: true,
 569           description: "Allows automatically follow moved following accounts"
 570         },
 571         pleroma_background_image: %Schema{
 572           type: :string,
 573           nullable: true,
 574           description: "Sets the background image of the user.",
 575           format: :binary
 576         },
 577         discoverable: %Schema{
 578           allOf: [BooleanLike],
 579           nullable: true,
 580           description:
 581             "Discovery of this account in search results and other services is allowed."
 582         },
 583         actor_type: ActorType
 584       },
 585       example: %{
 586         bot: false,
 587         display_name: "cofe",
 588         note: "foobar",
 589         fields_attributes: [%{name: "foo", value: "bar"}],
 590         no_rich_text: false,
 591         hide_followers: true,
 592         hide_follows: false,
 593         hide_followers_count: false,
 594         hide_follows_count: false,
 595         hide_favorites: false,
 596         show_role: false,
 597         default_scope: "private",
 598         pleroma_settings_store: %{"pleroma-fe" => %{"key" => "val"}},
 599         skip_thread_containment: false,
 600         allow_following_move: false,
 601         discoverable: false,
 602         actor_type: "Person"
 603       }
 604     }
 605   end
 606
 607   def array_of_accounts do
 608     %Schema{
 609       title: "ArrayOfAccounts",
 610       type: :array,
 611       items: Account,
 612       example: [Account.schema().example]
 613     }
 614   end
 615
 616   defp array_of_relationships do
 617     %Schema{
 618       title: "ArrayOfRelationships",
 619       description: "Response schema for account relationships",
 620       type: :array,
 621       items: AccountRelationship,
 622       example: [
 623         %{
 624           "id" => "1",
 625           "following" => true,
 626           "showing_reblogs" => true,
 627           "followed_by" => true,
 628           "blocking" => false,
 629           "blocked_by" => true,
 630           "muting" => false,
 631           "muting_notifications" => false,
 632           "requested" => false,
 633           "domain_blocking" => false,
 634           "subscribing" => false,
 635           "endorsed" => true
 636         },
 637         %{
 638           "id" => "2",
 639           "following" => true,
 640           "showing_reblogs" => true,
 641           "followed_by" => true,
 642           "blocking" => false,
 643           "blocked_by" => true,
 644           "muting" => true,
 645           "muting_notifications" => false,
 646           "requested" => true,
 647           "domain_blocking" => false,
 648           "subscribing" => false,
 649           "endorsed" => false
 650         },
 651         %{
 652           "id" => "3",
 653           "following" => true,
 654           "showing_reblogs" => true,
 655           "followed_by" => true,
 656           "blocking" => true,
 657           "blocked_by" => false,
 658           "muting" => true,
 659           "muting_notifications" => false,
 660           "requested" => false,
 661           "domain_blocking" => true,
 662           "subscribing" => true,
 663           "endorsed" => false
 664         }
 665       ]
 666     }
 667   end
 668
 669   defp follow_by_uri_request do
 670     %Schema{
 671       title: "AccountFollowsRequest",
 672       description: "POST body for muting an account",
 673       type: :object,
 674       properties: %{
 675         uri: %Schema{type: :string, nullable: true, format: :uri}
 676       },
 677       required: [:uri]
 678     }
 679   end
 680
 681   defp mute_request do
 682     %Schema{
 683       title: "AccountMuteRequest",
 684       description: "POST body for muting an account",
 685       type: :object,
 686       properties: %{
 687         notifications: %Schema{
 688           allOf: [BooleanLike],
 689           nullable: true,
 690           description: "Mute notifications in addition to statuses? Defaults to true.",
 691           default: true
 692         }
 693       },
 694       example: %{
 695         "notifications" => true
 696       }
 697     }
 698   end
 699
 700   defp array_of_lists do
 701     %Schema{
 702       title: "ArrayOfLists",
 703       description: "Response schema for lists",
 704       type: :array,
 705       items: List,
 706       example: [
 707         %{"id" => "123", "title" => "my list"},
 708         %{"id" => "1337", "title" => "anotehr list"}
 709       ]
 710     }
 711   end
 712
 713   defp array_of_statuses do
 714     %Schema{
 715       title: "ArrayOfStatuses",
 716       type: :array,
 717       items: Status
 718     }
 719   end
 720
 721   defp attribute_field do
 722     %Schema{
 723       title: "AccountAttributeField",
 724       description: "Request schema for account custom fields",
 725       type: :object,
 726       properties: %{
 727         name: %Schema{type: :string},
 728         value: %Schema{type: :string}
 729       },
 730       required: [:name, :value],
 731       example: %{
 732         "name" => "Website",
 733         "value" => "https://pleroma.com"
 734       }
 735     }
 736   end
 737 end