git.squeep.com Git - akkoma/blob - lib/pleroma/web/api_spec/operations/subscription_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.SubscriptionOperation do
   6   alias OpenApiSpex.Operation
   7   alias OpenApiSpex.Schema
   8   alias Pleroma.Web.ApiSpec.Helpers
   9   alias Pleroma.Web.ApiSpec.Schemas.ApiError
  10   alias Pleroma.Web.ApiSpec.Schemas.PushSubscription
  11
  12   def open_api_operation(action) do
  13     operation = String.to_existing_atom("#{action}_operation")
  14     apply(__MODULE__, operation, [])
  15   end
  16
  17   def create_operation do
  18     %Operation{
  19       tags: ["Push Subscriptions"],
  20       summary: "Subscribe to push notifications",
  21       description:
  22         "Add a Web Push API subscription to receive notifications. Each access token can have one push subscription. If you create a new subscription, the old subscription is deleted.",
  23       operationId: "SubscriptionController.create",
  24       security: [%{"oAuth" => ["push"]}],
  25       requestBody: Helpers.request_body("Parameters", create_request(), required: true),
  26       responses: %{
  27         200 => Operation.response("Push Subscription", "application/json", PushSubscription),
  28         400 => Operation.response("Error", "application/json", ApiError),
  29         403 => Operation.response("Error", "application/json", ApiError)
  30       }
  31     }
  32   end
  33
  34   def show_operation do
  35     %Operation{
  36       tags: ["Push Subscriptions"],
  37       summary: "Get current subscription",
  38       description: "View the PushSubscription currently associated with this access token.",
  39       operationId: "SubscriptionController.show",
  40       security: [%{"oAuth" => ["push"]}],
  41       responses: %{
  42         200 => Operation.response("Push Subscription", "application/json", PushSubscription),
  43         403 => Operation.response("Error", "application/json", ApiError),
  44         404 => Operation.response("Error", "application/json", ApiError)
  45       }
  46     }
  47   end
  48
  49   def update_operation do
  50     %Operation{
  51       tags: ["Push Subscriptions"],
  52       summary: "Change types of notifications",
  53       description:
  54         "Updates the current push subscription. Only the data part can be updated. To change fundamentals, a new subscription must be created instead.",
  55       operationId: "SubscriptionController.update",
  56       security: [%{"oAuth" => ["push"]}],
  57       requestBody: Helpers.request_body("Parameters", update_request(), required: true),
  58       responses: %{
  59         200 => Operation.response("Push Subscription", "application/json", PushSubscription),
  60         403 => Operation.response("Error", "application/json", ApiError)
  61       }
  62     }
  63   end
  64
  65   def delete_operation do
  66     %Operation{
  67       tags: ["Push Subscriptions"],
  68       summary: "Remove current subscription",
  69       description: "Removes the current Web Push API subscription.",
  70       operationId: "SubscriptionController.delete",
  71       security: [%{"oAuth" => ["push"]}],
  72       responses: %{
  73         200 => Operation.response("Empty object", "application/json", %Schema{type: :object}),
  74         403 => Operation.response("Error", "application/json", ApiError),
  75         404 => Operation.response("Error", "application/json", ApiError)
  76       }
  77     }
  78   end
  79
  80   defp create_request do
  81     %Schema{
  82       title: "SubscriptionCreateRequest",
  83       description: "POST body for creating a push subscription",
  84       type: :object,
  85       properties: %{
  86         subscription: %Schema{
  87           type: :object,
  88           properties: %{
  89             endpoint: %Schema{
  90               type: :string,
  91               description: "Endpoint URL that is called when a notification event occurs."
  92             },
  93             keys: %Schema{
  94               type: :object,
  95               properties: %{
  96                 p256dh: %Schema{
  97                   type: :string,
  98                   description:
  99                     "User agent public key. Base64 encoded string of public key of ECDH key using `prime256v1` curve."
 100                 },
 101                 auth: %Schema{
 102                   type: :string,
 103                   description: "Auth secret. Base64 encoded string of 16 bytes of random data."
 104                 }
 105               },
 106               required: [:p256dh, :auth]
 107             }
 108           },
 109           required: [:endpoint, :keys]
 110         },
 111         data: %Schema{
 112           nullable: true,
 113           type: :object,
 114           properties: %{
 115             alerts: %Schema{
 116               nullable: true,
 117               type: :object,
 118               properties: %{
 119                 follow: %Schema{
 120                   type: :boolean,
 121                   nullable: true,
 122                   description: "Receive follow notifications?"
 123                 },
 124                 favourite: %Schema{
 125                   type: :boolean,
 126                   nullable: true,
 127                   description: "Receive favourite notifications?"
 128                 },
 129                 reblog: %Schema{
 130                   type: :boolean,
 131                   nullable: true,
 132                   description: "Receive reblog notifications?"
 133                 },
 134                 mention: %Schema{
 135                   type: :boolean,
 136                   nullable: true,
 137                   description: "Receive mention notifications?"
 138                 },
 139                 poll: %Schema{
 140                   type: :boolean,
 141                   nullable: true,
 142                   description: "Receive poll notifications?"
 143                 }
 144               }
 145             }
 146           }
 147         }
 148       },
 149       required: [:subscription],
 150       example: %{
 151         "subscription" => %{
 152           "endpoint" => "https://example.com/example/1234",
 153           "keys" => %{
 154             "auth" => "8eDyX_uCN0XRhSbY5hs7Hg==",
 155             "p256dh" =>
 156               "BCIWgsnyXDv1VkhqL2P7YRBvdeuDnlwAPT2guNhdIoW3IP7GmHh1SMKPLxRf7x8vJy6ZFK3ol2ohgn_-0yP7QQA="
 157           }
 158         },
 159         "data" => %{
 160           "alerts" => %{
 161             "follow" => true,
 162             "mention" => true,
 163             "poll" => false
 164           }
 165         }
 166       }
 167     }
 168   end
 169
 170   defp update_request do
 171     %Schema{
 172       title: "SubscriptionUpdateRequest",
 173       type: :object,
 174       properties: %{
 175         data: %Schema{
 176           nullable: true,
 177           type: :object,
 178           properties: %{
 179             alerts: %Schema{
 180               nullable: true,
 181               type: :object,
 182               properties: %{
 183                 follow: %Schema{
 184                   type: :boolean,
 185                   nullable: true,
 186                   description: "Receive follow notifications?"
 187                 },
 188                 favourite: %Schema{
 189                   type: :boolean,
 190                   nullable: true,
 191                   description: "Receive favourite notifications?"
 192                 },
 193                 reblog: %Schema{
 194                   type: :boolean,
 195                   nullable: true,
 196                   description: "Receive reblog notifications?"
 197                 },
 198                 mention: %Schema{
 199                   type: :boolean,
 200                   nullable: true,
 201                   description: "Receive mention notifications?"
 202                 },
 203                 poll: %Schema{
 204                   type: :boolean,
 205                   nullable: true,
 206                   description: "Receive poll notifications?"
 207                 }
 208               }
 209             }
 210           }
 211         }
 212       },
 213       example: %{
 214         "data" => %{
 215           "alerts" => %{
 216             "follow" => true,
 217             "favourite" => true,
 218             "reblog" => true,
 219             "mention" => true,
 220             "poll" => true
 221           }
 222         }
 223       }
 224     }
 225   end
 226 end