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           type: :object,
 113           properties: %{
 114             alerts: %Schema{
 115               type: :object,
 116               properties: %{
 117                 follow: %Schema{type: :boolean, description: "Receive follow notifications?"},
 118                 favourite: %Schema{
 119                   type: :boolean,
 120                   description: "Receive favourite notifications?"
 121                 },
 122                 reblog: %Schema{type: :boolean, description: "Receive reblog notifications?"},
 123                 mention: %Schema{type: :boolean, description: "Receive mention notifications?"},
 124                 poll: %Schema{type: :boolean, description: "Receive poll notifications?"}
 125               }
 126             }
 127           }
 128         }
 129       },
 130       required: [:subscription],
 131       example: %{
 132         "subscription" => %{
 133           "endpoint" => "https://example.com/example/1234",
 134           "keys" => %{
 135             "auth" => "8eDyX_uCN0XRhSbY5hs7Hg==",
 136             "p256dh" =>
 137               "BCIWgsnyXDv1VkhqL2P7YRBvdeuDnlwAPT2guNhdIoW3IP7GmHh1SMKPLxRf7x8vJy6ZFK3ol2ohgn_-0yP7QQA="
 138           }
 139         },
 140         "data" => %{
 141           "alerts" => %{
 142             "follow" => true,
 143             "mention" => true,
 144             "poll" => false
 145           }
 146         }
 147       }
 148     }
 149   end
 150
 151   defp update_request do
 152     %Schema{
 153       title: "SubscriptionUpdateRequest",
 154       type: :object,
 155       properties: %{
 156         data: %Schema{
 157           type: :object,
 158           properties: %{
 159             alerts: %Schema{
 160               type: :object,
 161               properties: %{
 162                 follow: %Schema{type: :boolean, description: "Receive follow notifications?"},
 163                 favourite: %Schema{
 164                   type: :boolean,
 165                   description: "Receive favourite notifications?"
 166                 },
 167                 reblog: %Schema{type: :boolean, description: "Receive reblog notifications?"},
 168                 mention: %Schema{type: :boolean, description: "Receive mention notifications?"},
 169                 poll: %Schema{type: :boolean, description: "Receive poll notifications?"}
 170               }
 171             }
 172           }
 173         }
 174       },
 175       example: %{
 176         "data" => %{
 177           "alerts" => %{
 178             "follow" => true,
 179             "favourite" => true,
 180             "reblog" => true,
 181             "mention" => true,
 182             "poll" => true
 183           }
 184         }
 185       }
 186     }
 187   end
 188 end