git.squeep.com Git - akkoma/blob - lib/pleroma/web/api_spec/operations/notification_operation.ex

   1 # Pleroma: A lightweight social networking server
   2 # Copyright © 2017-2021 Pleroma Authors <https://pleroma.social/>
   3 # SPDX-License-Identifier: AGPL-3.0-only
   4
   5 defmodule Pleroma.Web.ApiSpec.NotificationOperation do
   6   alias OpenApiSpex.Operation
   7   alias OpenApiSpex.Operation
   8   alias OpenApiSpex.Schema
   9   alias Pleroma.Web.ApiSpec.Schemas.Account
  10   alias Pleroma.Web.ApiSpec.Schemas.ApiError
  11   alias Pleroma.Web.ApiSpec.Schemas.BooleanLike
  12   alias Pleroma.Web.ApiSpec.Schemas.Status
  13   alias Pleroma.Web.ApiSpec.Schemas.VisibilityScope
  14
  15   import Pleroma.Web.ApiSpec.Helpers
  16
  17   def open_api_operation(action) do
  18     operation = String.to_existing_atom("#{action}_operation")
  19     apply(__MODULE__, operation, [])
  20   end
  21
  22   def index_operation do
  23     %Operation{
  24       tags: ["Notifications"],
  25       summary: "Retrieve a list of notifications",
  26       description:
  27         "Notifications concerning the user. This API returns Link headers containing links to the next/previous page. However, the links can also be constructed dynamically using query params and `id` values.",
  28       operationId: "NotificationController.index",
  29       security: [%{"oAuth" => ["read:notifications"]}],
  30       parameters:
  31         [
  32           Operation.parameter(
  33             :exclude_types,
  34             :query,
  35             %Schema{type: :array, items: notification_type()},
  36             "Array of types to exclude"
  37           ),
  38           Operation.parameter(
  39             :account_id,
  40             :query,
  41             %Schema{type: :string},
  42             "Return only notifications received from this account"
  43           ),
  44           Operation.parameter(
  45             :exclude_visibilities,
  46             :query,
  47             %Schema{type: :array, items: VisibilityScope},
  48             "Exclude the notifications for activities with the given visibilities"
  49           ),
  50           Operation.parameter(
  51             :include_types,
  52             :query,
  53             %Schema{type: :array, items: notification_type()},
  54             "Include the notifications for activities with the given types"
  55           ),
  56           Operation.parameter(
  57             :with_muted,
  58             :query,
  59             BooleanLike,
  60             "Include the notifications from muted users"
  61           )
  62         ] ++ pagination_params(),
  63       responses: %{
  64         200 =>
  65           Operation.response("Array of notifications", "application/json", %Schema{
  66             type: :array,
  67             items: notification()
  68           }),
  69         404 => Operation.response("Error", "application/json", ApiError)
  70       }
  71     }
  72   end
  73
  74   def show_operation do
  75     %Operation{
  76       tags: ["Notifications"],
  77       summary: "Retrieve a notification",
  78       description: "View information about a notification with a given ID.",
  79       operationId: "NotificationController.show",
  80       security: [%{"oAuth" => ["read:notifications"]}],
  81       parameters: [id_param()],
  82       responses: %{
  83         200 => Operation.response("Notification", "application/json", notification())
  84       }
  85     }
  86   end
  87
  88   def clear_operation do
  89     %Operation{
  90       tags: ["Notifications"],
  91       summary: "Dismiss all notifications",
  92       description: "Clear all notifications from the server.",
  93       operationId: "NotificationController.clear",
  94       security: [%{"oAuth" => ["write:notifications"]}],
  95       responses: %{200 => empty_object_response()}
  96     }
  97   end
  98
  99   def dismiss_operation do
 100     %Operation{
 101       tags: ["Notifications"],
 102       summary: "Dismiss a notification",
 103       description: "Clear a single notification from the server.",
 104       operationId: "NotificationController.dismiss",
 105       parameters: [id_param()],
 106       security: [%{"oAuth" => ["write:notifications"]}],
 107       responses: %{200 => empty_object_response()}
 108     }
 109   end
 110
 111   def dismiss_via_body_operation do
 112     %Operation{
 113       tags: ["Notifications"],
 114       summary: "Dismiss a single notification",
 115       deprecated: true,
 116       description: "Clear a single notification from the server.",
 117       operationId: "NotificationController.dismiss_via_body",
 118       requestBody:
 119         request_body(
 120           "Parameters",
 121           %Schema{type: :object, properties: %{id: %Schema{type: :string}}},
 122           required: true
 123         ),
 124       security: [%{"oAuth" => ["write:notifications"]}],
 125       responses: %{200 => empty_object_response()}
 126     }
 127   end
 128
 129   def destroy_multiple_operation do
 130     %Operation{
 131       tags: ["Notifications"],
 132       summary: "Dismiss multiple notifications",
 133       operationId: "NotificationController.destroy_multiple",
 134       security: [%{"oAuth" => ["write:notifications"]}],
 135       parameters: [
 136         Operation.parameter(
 137           :ids,
 138           :query,
 139           %Schema{type: :array, items: %Schema{type: :string}},
 140           "Array of notification IDs to dismiss",
 141           required: true
 142         )
 143       ],
 144       responses: %{200 => empty_object_response()}
 145     }
 146   end
 147
 148   def notification do
 149     %Schema{
 150       title: "Notification",
 151       description: "Response schema for a notification",
 152       type: :object,
 153       properties: %{
 154         id: %Schema{type: :string},
 155         type: notification_type(),
 156         created_at: %Schema{type: :string, format: :"date-time"},
 157         account: %Schema{
 158           allOf: [Account],
 159           description: "The account that performed the action that generated the notification."
 160         },
 161         status: %Schema{
 162           allOf: [Status],
 163           description:
 164             "Status that was the object of the notification, e.g. in mentions, reblogs, favourites, or polls.",
 165           nullable: true
 166         },
 167         pleroma: %Schema{
 168           type: :object,
 169           properties: %{
 170             is_seen: %Schema{type: :boolean},
 171             is_muted: %Schema{type: :boolean}
 172           }
 173         }
 174       },
 175       example: %{
 176         "id" => "34975861",
 177         "type" => "mention",
 178         "created_at" => "2019-11-23T07:49:02.064Z",
 179         "account" => Account.schema().example,
 180         "status" => Status.schema().example,
 181         "pleroma" => %{"is_seen" => false, "is_muted" => false}
 182       }
 183     }
 184   end
 185
 186   defp notification_type do
 187     %Schema{
 188       type: :string,
 189       enum: [
 190         "follow",
 191         "favourite",
 192         "reblog",
 193         "mention",
 194         "pleroma:emoji_reaction",
 195         "pleroma:chat_mention",
 196         "pleroma:report",
 197         "move",
 198         "follow_request",
 199         "poll"
 200       ],
 201       description: """
 202       The type of event that resulted in the notification.
 203
 204       - `follow` - Someone followed you
 205       - `mention` - Someone mentioned you in their status
 206       - `reblog` - Someone boosted one of your statuses
 207       - `favourite` - Someone favourited one of your statuses
 208       - `poll` - A poll you have voted in or created has ended
 209       - `move` - Someone moved their account
 210       - `pleroma:emoji_reaction` - Someone reacted with emoji to your status
 211       - `pleroma:chat_mention` - Someone mentioned you in a chat message
 212       - `pleroma:report` - Someone was reported
 213       """
 214     }
 215   end
 216
 217   defp id_param do
 218     Operation.parameter(:id, :path, :string, "Notification ID",
 219       example: "123",
 220       required: true
 221     )
 222   end
 223 end