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 destroy_multiple_operation do
 112     %Operation{
 113       tags: ["Notifications"],
 114       summary: "Dismiss multiple notifications",
 115       operationId: "NotificationController.destroy_multiple",
 116       security: [%{"oAuth" => ["write:notifications"]}],
 117       parameters: [
 118         Operation.parameter(
 119           :ids,
 120           :query,
 121           %Schema{type: :array, items: %Schema{type: :string}},
 122           "Array of notification IDs to dismiss",
 123           required: true
 124         )
 125       ],
 126       responses: %{200 => empty_object_response()}
 127     }
 128   end
 129
 130   def notification do
 131     %Schema{
 132       title: "Notification",
 133       description: "Response schema for a notification",
 134       type: :object,
 135       properties: %{
 136         id: %Schema{type: :string},
 137         type: notification_type(),
 138         created_at: %Schema{type: :string, format: :"date-time"},
 139         account: %Schema{
 140           allOf: [Account],
 141           description: "The account that performed the action that generated the notification."
 142         },
 143         status: %Schema{
 144           allOf: [Status],
 145           description:
 146             "Status that was the object of the notification, e.g. in mentions, reblogs, favourites, or polls.",
 147           nullable: true
 148         },
 149         pleroma: %Schema{
 150           type: :object,
 151           properties: %{
 152             is_seen: %Schema{type: :boolean},
 153             is_muted: %Schema{type: :boolean}
 154           }
 155         }
 156       },
 157       example: %{
 158         "id" => "34975861",
 159         "type" => "mention",
 160         "created_at" => "2019-11-23T07:49:02.064Z",
 161         "account" => Account.schema().example,
 162         "status" => Status.schema().example,
 163         "pleroma" => %{"is_seen" => false, "is_muted" => false}
 164       }
 165     }
 166   end
 167
 168   defp notification_type do
 169     %Schema{
 170       type: :string,
 171       enum: [
 172         "follow",
 173         "favourite",
 174         "reblog",
 175         "mention",
 176         "pleroma:emoji_reaction",
 177         "pleroma:chat_mention",
 178         "pleroma:report",
 179         "move",
 180         "follow_request",
 181         "poll"
 182       ],
 183       description: """
 184       The type of event that resulted in the notification.
 185
 186       - `follow` - Someone followed you
 187       - `mention` - Someone mentioned you in their status
 188       - `reblog` - Someone boosted one of your statuses
 189       - `favourite` - Someone favourited one of your statuses
 190       - `poll` - A poll you have voted in or created has ended
 191       - `move` - Someone moved their account
 192       - `pleroma:emoji_reaction` - Someone reacted with emoji to your status
 193       - `pleroma:chat_mention` - Someone mentioned you in a chat message
 194       - `pleroma:report` - Someone was reported
 195       """
 196     }
 197   end
 198
 199   defp id_param do
 200     Operation.parameter(:id, :path, :string, "Notification ID",
 201       example: "123",
 202       required: true
 203     )
 204   end
 205 end