account_operation.ex 22.4 KB
Newer Older
1
2
3
4
5
6
# Pleroma: A lightweight social networking server
# Copyright © 2017-2020 Pleroma Authors <https://pleroma.social/>
# SPDX-License-Identifier: AGPL-3.0-only

defmodule Pleroma.Web.ApiSpec.AccountOperation do
  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
12
  alias Pleroma.Web.ApiSpec.Schemas.ActorType
  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
19
  import Pleroma.Web.ApiSpec.Helpers

20
21
22
23
24
25
26
27
28
29
30
31
32
33
  @spec open_api_operation(atom) :: Operation.t()
  def open_api_operation(action) do
    operation = String.to_existing_atom("#{action}_operation")
    apply(__MODULE__, operation, [])
  end

  @spec create_operation() :: Operation.t()
  def create_operation do
    %Operation{
      tags: ["accounts"],
      summary: "Register an account",
      description:
        "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.",
      operationId: "AccountController.create",
34
      requestBody: request_body("Parameters", create_request(), required: true),
35
      responses: %{
36
        200 => Operation.response("Account", "application/json", create_response()),
37
38
39
        400 => Operation.response("Error", "application/json", ApiError),
        403 => Operation.response("Error", "application/json", ApiError),
        429 => Operation.response("Error", "application/json", ApiError)
40
41
42
43
44
      }
    }
  end

  def verify_credentials_operation do
45
46
47
48
49
50
51
52
53
54
    %Operation{
      tags: ["accounts"],
      description: "Test to make sure that the user token works.",
      summary: "Verify account credentials",
      operationId: "AccountController.verify_credentials",
      security: [%{"oAuth" => ["read:accounts"]}],
      responses: %{
        200 => Operation.response("Account", "application/json", Account)
      }
    }
55
56
57
  end

  def update_credentials_operation do
58
59
60
61
62
63
    %Operation{
      tags: ["accounts"],
      summary: "Update account credentials",
      description: "Update the user's display and preferences.",
      operationId: "AccountController.update_credentials",
      security: [%{"oAuth" => ["write:accounts"]}],
64
      requestBody: request_body("Parameters", update_creadentials_request(), required: true),
65
      responses: %{
66
67
        200 => Operation.response("Account", "application/json", Account),
        403 => Operation.response("Error", "application/json", ApiError)
68
69
      }
    }
70
71
72
  end

  def relationships_operation do
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
    %Operation{
      tags: ["accounts"],
      summary: "Check relationships to other accounts",
      operationId: "AccountController.relationships",
      description: "Find out whether a given account is followed, blocked, muted, etc.",
      security: [%{"oAuth" => ["read:follows"]}],
      parameters: [
        Operation.parameter(
          :id,
          :query,
          %Schema{
            oneOf: [%Schema{type: :array, items: %Schema{type: :string}}, %Schema{type: :string}]
          },
          "Account IDs",
          example: "123"
        )
      ],
      responses: %{
91
        200 => Operation.response("Account", "application/json", array_of_relationships())
92
93
      }
    }
94
95
96
  end

  def show_operation do
97
98
99
100
101
    %Operation{
      tags: ["accounts"],
      summary: "Account",
      operationId: "AccountController.show",
      description: "View information about a profile.",
102
      parameters: [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}],
103
      responses: %{
104
105
        200 => Operation.response("Account", "application/json", Account),
        404 => Operation.response("Error", "application/json", ApiError)
106
107
      }
    }
108
109
110
  end

  def statuses_operation do
111
112
113
114
115
116
    %Operation{
      tags: ["accounts"],
      summary: "Statuses",
      operationId: "AccountController.statuses",
      description:
        "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
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
      parameters:
        [
          %Reference{"$ref": "#/components/parameters/accountIdOrNickname"},
          Operation.parameter(:pinned, :query, BooleanLike, "Include only pinned statuses"),
          Operation.parameter(:tagged, :query, :string, "With tag"),
          Operation.parameter(
            :only_media,
            :query,
            BooleanLike,
            "Include only statuses with media attached"
          ),
          Operation.parameter(
            :with_muted,
            :query,
            BooleanLike,
            "Include statuses from muted acccounts."
          ),
          Operation.parameter(:exclude_reblogs, :query, BooleanLike, "Exclude reblogs"),
135
          Operation.parameter(:exclude_replies, :query, BooleanLike, "Exclude replies"),
136
137
138
139
140
141
142
          Operation.parameter(
            :exclude_visibilities,
            :query,
            %Schema{type: :array, items: VisibilityScope},
            "Exclude visibilities"
          )
        ] ++ 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
149
150
  end

  def followers_operation do
151
152
153
154
155
156
157
    %Operation{
      tags: ["accounts"],
      summary: "Followers",
      operationId: "AccountController.followers",
      security: [%{"oAuth" => ["read:accounts"]}],
      description:
        "Accounts which follow the given account, if network is not hidden by the account owner.",
158
159
      parameters:
        [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}] ++ pagination_params(),
160
      responses: %{
161
        200 => Operation.response("Accounts", "application/json", array_of_accounts())
162
163
164
165
166
167
168
169
170
171
172
173
      }
    }
  end

  def following_operation do
    %Operation{
      tags: ["accounts"],
      summary: "Following",
      operationId: "AccountController.following",
      security: [%{"oAuth" => ["read:accounts"]}],
      description:
        "Accounts which the given account is following, if network is not hidden by the account owner.",
174
175
      parameters:
        [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}] ++ pagination_params(),
176
      responses: %{200 => Operation.response("Accounts", "application/json", array_of_accounts())}
177
    }
178
179
  end

180
181
182
183
184
185
186
  def lists_operation do
    %Operation{
      tags: ["accounts"],
      summary: "Lists containing this account",
      operationId: "AccountController.lists",
      security: [%{"oAuth" => ["read:lists"]}],
      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
191
192
193
194
195
196
197
198
    }
  end

  def follow_operation do
    %Operation{
      tags: ["accounts"],
      summary: "Follow",
      operationId: "AccountController.follow",
      security: [%{"oAuth" => ["follow", "write:follows"]}],
      description: "Follow the given account",
199
      parameters: [
200
201
202
203
204
205
206
        %Reference{"$ref": "#/components/parameters/accountIdOrNickname"},
        Operation.parameter(
          :reblogs,
          :query,
          BooleanLike,
          "Receive this account's reblogs in home timeline? Defaults to true."
        )
207
208
      ],
      responses: %{
209
210
211
        200 => Operation.response("Relationship", "application/json", AccountRelationship),
        400 => Operation.response("Error", "application/json", ApiError),
        404 => Operation.response("Error", "application/json", ApiError)
212
213
214
215
      }
    }
  end

216
217
218
219
220
221
222
223
224
  def unfollow_operation do
    %Operation{
      tags: ["accounts"],
      summary: "Unfollow",
      operationId: "AccountController.unfollow",
      security: [%{"oAuth" => ["follow", "write:follows"]}],
      description: "Unfollow the given account",
      parameters: [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}],
      responses: %{
225
226
227
        200 => Operation.response("Relationship", "application/json", AccountRelationship),
        400 => Operation.response("Error", "application/json", ApiError),
        404 => Operation.response("Error", "application/json", ApiError)
228
229
230
231
      }
    }
  end

232
233
234
235
236
237
  def mute_operation do
    %Operation{
      tags: ["accounts"],
      summary: "Mute",
      operationId: "AccountController.mute",
      security: [%{"oAuth" => ["follow", "write:mutes"]}],
238
      requestBody: request_body("Parameters", mute_request()),
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
      description:
        "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).",
      parameters: [
        %Reference{"$ref": "#/components/parameters/accountIdOrNickname"},
        Operation.parameter(
          :notifications,
          :query,
          %Schema{allOf: [BooleanLike], default: true},
          "Mute notifications in addition to statuses? Defaults to `true`."
        )
      ],
      responses: %{
        200 => Operation.response("Relationship", "application/json", AccountRelationship)
      }
    }
  end

  def unmute_operation do
    %Operation{
      tags: ["accounts"],
      summary: "Unmute",
      operationId: "AccountController.unmute",
      security: [%{"oAuth" => ["follow", "write:mutes"]}],
      description: "Unmute the given account.",
      parameters: [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}],
      responses: %{
        200 => Operation.response("Relationship", "application/json", AccountRelationship)
      }
    }
  end

270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
  def block_operation do
    %Operation{
      tags: ["accounts"],
      summary: "Block",
      operationId: "AccountController.block",
      security: [%{"oAuth" => ["follow", "write:blocks"]}],
      description:
        "Block the given account. Clients should filter statuses from this account if received (e.g. due to a boost in the Home timeline)",
      parameters: [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}],
      responses: %{
        200 => Operation.response("Relationship", "application/json", AccountRelationship)
      }
    }
  end

  def unblock_operation do
    %Operation{
      tags: ["accounts"],
      summary: "Unblock",
      operationId: "AccountController.unblock",
      security: [%{"oAuth" => ["follow", "write:blocks"]}],
      description: "Unblock the given account.",
      parameters: [%Reference{"$ref": "#/components/parameters/accountIdOrNickname"}],
      responses: %{
        200 => Operation.response("Relationship", "application/json", AccountRelationship)
      }
    }
  end

Ivan Tashkinov's avatar
Ivan Tashkinov committed
299
  def follow_by_uri_operation do
300
301
    %Operation{
      tags: ["accounts"],
Ivan Tashkinov's avatar
Ivan Tashkinov committed
302
      summary: "Follow by URI",
303
304
      operationId: "AccountController.follows",
      security: [%{"oAuth" => ["follow", "write:follows"]}],
Ivan Tashkinov's avatar
Ivan Tashkinov committed
305
      requestBody: request_body("Parameters", follow_by_uri_request(), required: true),
306
      responses: %{
307
308
309
        200 => Operation.response("Account", "application/json", AccountRelationship),
        400 => Operation.response("Error", "application/json", ApiError),
        404 => Operation.response("Error", "application/json", ApiError)
310
311
312
313
      }
    }
  end

314
315
316
317
318
319
320
321
  def mutes_operation do
    %Operation{
      tags: ["accounts"],
      summary: "Muted accounts",
      operationId: "AccountController.mutes",
      description: "Accounts the user has muted.",
      security: [%{"oAuth" => ["follow", "read:mutes"]}],
      responses: %{
322
        200 => Operation.response("Accounts", "application/json", array_of_accounts())
323
324
325
326
327
328
329
330
331
332
333
334
      }
    }
  end

  def blocks_operation do
    %Operation{
      tags: ["accounts"],
      summary: "Blocked users",
      operationId: "AccountController.blocks",
      description: "View your blocks. See also accounts/:id/{block,unblock}",
      security: [%{"oAuth" => ["read:blocks"]}],
      responses: %{
335
        200 => Operation.response("Accounts", "application/json", array_of_accounts())
336
337
338
339
340
341
342
343
344
345
346
347
      }
    }
  end

  def endorsements_operation do
    %Operation{
      tags: ["accounts"],
      summary: "Endorsements",
      operationId: "AccountController.endorsements",
      description: "Not implemented",
      security: [%{"oAuth" => ["read:accounts"]}],
      responses: %{
348
        200 => empty_array_response()
349
350
351
      }
    }
  end
352
353
354
355
356
357
358
359

  def identity_proofs_operation do
    %Operation{
      tags: ["accounts"],
      summary: "Identity proofs",
      operationId: "AccountController.identity_proofs",
      description: "Not implemented",
      responses: %{
360
        200 => empty_array_response()
361
362
363
      }
    }
  end
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558

  defp create_request do
    %Schema{
      title: "AccountCreateRequest",
      description: "POST body for creating an account",
      type: :object,
      properties: %{
        reason: %Schema{
          type: :string,
          description:
            "Text that will be reviewed by moderators if registrations require manual approval"
        },
        username: %Schema{type: :string, description: "The desired username for the account"},
        email: %Schema{
          type: :string,
          description:
            "The email address to be used for login. Required when `account_activation_required` is enabled.",
          format: :email
        },
        password: %Schema{
          type: :string,
          description: "The password to be used for login",
          format: :password
        },
        agreement: %Schema{
          type: :boolean,
          description:
            "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."
        },
        locale: %Schema{
          type: :string,
          description: "The language of the confirmation email that will be sent"
        },
        # Pleroma-specific properties:
        fullname: %Schema{type: :string, description: "Full name"},
        bio: %Schema{type: :string, description: "Bio", default: ""},
        captcha_solution: %Schema{
          type: :string,
          description: "Provider-specific captcha solution"
        },
        captcha_token: %Schema{type: :string, description: "Provider-specific captcha token"},
        captcha_answer_data: %Schema{type: :string, description: "Provider-specific captcha data"},
        token: %Schema{
          type: :string,
          description: "Invite token required when the registrations aren't public"
        }
      },
      required: [:username, :password, :agreement],
      example: %{
        "username" => "cofe",
        "email" => "cofe@example.com",
        "password" => "secret",
        "agreement" => "true",
        "bio" => "☕️"
      }
    }
  end

  defp create_response do
    %Schema{
      title: "AccountCreateResponse",
      description: "Response schema for an account",
      type: :object,
      properties: %{
        token_type: %Schema{type: :string},
        access_token: %Schema{type: :string},
        scope: %Schema{type: :array, items: %Schema{type: :string}},
        created_at: %Schema{type: :integer, format: :"date-time"}
      },
      example: %{
        "access_token" => "i9hAVVzGld86Pl5JtLtizKoXVvtTlSCJvwaugCxvZzk",
        "created_at" => 1_585_918_714,
        "scope" => ["read", "write", "follow", "push"],
        "token_type" => "Bearer"
      }
    }
  end

  defp update_creadentials_request do
    %Schema{
      title: "AccountUpdateCredentialsRequest",
      description: "POST body for creating an account",
      type: :object,
      properties: %{
        bot: %Schema{
          type: :boolean,
          description: "Whether the account has a bot flag."
        },
        display_name: %Schema{
          type: :string,
          description: "The display name to use for the profile."
        },
        note: %Schema{type: :string, description: "The account bio."},
        avatar: %Schema{
          type: :string,
          description: "Avatar image encoded using multipart/form-data",
          format: :binary
        },
        header: %Schema{
          type: :string,
          description: "Header image encoded using multipart/form-data",
          format: :binary
        },
        locked: %Schema{
          type: :boolean,
          description: "Whether manual approval of follow requests is required."
        },
        fields_attributes: %Schema{
          oneOf: [
            %Schema{type: :array, items: attribute_field()},
            %Schema{type: :object, additionalProperties: %Schema{type: attribute_field()}}
          ]
        },
        # NOTE: `source` field is not supported
        #
        # source: %Schema{
        #   type: :object,
        #   properties: %{
        #     privacy: %Schema{type: :string},
        #     sensitive: %Schema{type: :boolean},
        #     language: %Schema{type: :string}
        #   }
        # },

        # Pleroma-specific fields
        no_rich_text: %Schema{
          type: :boolean,
          description: "html tags are stripped from all statuses requested from the API"
        },
        hide_followers: %Schema{type: :boolean, description: "user's followers will be hidden"},
        hide_follows: %Schema{type: :boolean, description: "user's follows will be hidden"},
        hide_followers_count: %Schema{
          type: :boolean,
          description: "user's follower count will be hidden"
        },
        hide_follows_count: %Schema{
          type: :boolean,
          description: "user's follow count will be hidden"
        },
        hide_favorites: %Schema{
          type: :boolean,
          description: "user's favorites timeline will be hidden"
        },
        show_role: %Schema{
          type: :boolean,
          description: "user's role (e.g admin, moderator) will be exposed to anyone in the
        API"
        },
        default_scope: VisibilityScope,
        pleroma_settings_store: %Schema{
          type: :object,
          description: "Opaque user settings to be saved on the backend."
        },
        skip_thread_containment: %Schema{
          type: :boolean,
          description: "Skip filtering out broken threads"
        },
        allow_following_move: %Schema{
          type: :boolean,
          description: "Allows automatically follow moved following accounts"
        },
        pleroma_background_image: %Schema{
          type: :string,
          description: "Sets the background image of the user.",
          format: :binary
        },
        discoverable: %Schema{
          type: :boolean,
          description:
            "Discovery of this account in search results and other services is allowed."
        },
        actor_type: ActorType
      },
      example: %{
        bot: false,
        display_name: "cofe",
        note: "foobar",
        fields_attributes: [%{name: "foo", value: "bar"}],
        no_rich_text: false,
        hide_followers: true,
        hide_follows: false,
        hide_followers_count: false,
        hide_follows_count: false,
        hide_favorites: false,
        show_role: false,
        default_scope: "private",
        pleroma_settings_store: %{"pleroma-fe" => %{"key" => "val"}},
        skip_thread_containment: false,
        allow_following_move: false,
        discoverable: false,
        actor_type: "Person"
      }
    }
  end

559
  def array_of_accounts do
560
561
562
    %Schema{
      title: "ArrayOfAccounts",
      type: :array,
563
564
      items: Account,
      example: [Account.schema().example]
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
    }
  end

  defp array_of_relationships do
    %Schema{
      title: "ArrayOfRelationships",
      description: "Response schema for account relationships",
      type: :array,
      items: AccountRelationship,
      example: [
        %{
          "id" => "1",
          "following" => true,
          "showing_reblogs" => true,
          "followed_by" => true,
          "blocking" => false,
          "blocked_by" => true,
          "muting" => false,
          "muting_notifications" => false,
          "requested" => false,
          "domain_blocking" => false,
          "subscribing" => false,
          "endorsed" => true
        },
        %{
          "id" => "2",
          "following" => true,
          "showing_reblogs" => true,
          "followed_by" => true,
          "blocking" => false,
          "blocked_by" => true,
          "muting" => true,
          "muting_notifications" => false,
          "requested" => true,
          "domain_blocking" => false,
          "subscribing" => false,
          "endorsed" => false
        },
        %{
          "id" => "3",
          "following" => true,
          "showing_reblogs" => true,
          "followed_by" => true,
          "blocking" => true,
          "blocked_by" => false,
          "muting" => true,
          "muting_notifications" => false,
          "requested" => false,
          "domain_blocking" => true,
          "subscribing" => true,
          "endorsed" => false
        }
      ]
    }
  end

Ivan Tashkinov's avatar
Ivan Tashkinov committed
621
  defp follow_by_uri_request do
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
    %Schema{
      title: "AccountFollowsRequest",
      description: "POST body for muting an account",
      type: :object,
      properties: %{
        uri: %Schema{type: :string, format: :uri}
      },
      required: [:uri]
    }
  end

  defp mute_request do
    %Schema{
      title: "AccountMuteRequest",
      description: "POST body for muting an account",
      type: :object,
      properties: %{
        notifications: %Schema{
          type: :boolean,
          description: "Mute notifications in addition to statuses? Defaults to true.",
          default: true
        }
      },
      example: %{
        "notifications" => true
      }
    }
  end

  defp array_of_lists do
    %Schema{
      title: "ArrayOfLists",
      description: "Response schema for lists",
      type: :array,
656
      items: List,
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
      example: [
        %{"id" => "123", "title" => "my list"},
        %{"id" => "1337", "title" => "anotehr list"}
      ]
    }
  end

  defp array_of_statuses do
    %Schema{
      title: "ArrayOfStatuses",
      type: :array,
      items: Status
    }
  end

  defp attribute_field do
    %Schema{
      title: "AccountAttributeField",
      description: "Request schema for account custom fields",
      type: :object,
      properties: %{
        name: %Schema{type: :string},
        value: %Schema{type: :string}
      },
      required: [:name, :value],
      example: %{
        "name" => "Website",
        "value" => "https://pleroma.com"
      }
    }
  end
688
end