fix(webhooks): merge develop and harden delivery

lib/pleroma/web/api_spec/operations/admin/webhook_operation.ex

@@ -57,7 +57,7 @@ defmodule Pleroma.Web.ApiSpec.Admin.WebhookOperation do
             type: :object,
             required: [:url, :events],
             properties: %{
-              url: %Schema{type: :string, format: :uri},
+              url: %Schema{type: :string, format: :uri, maxLength: 255},
               events: event_type(min_items: 1),
               enabled: %Schema{type: :boolean}
             },
@@ -84,7 +84,7 @@ defmodule Pleroma.Web.ApiSpec.Admin.WebhookOperation do
             description: "POST body for updating a webhook",
             type: :object,
             properties: %{
-              url: %Schema{type: :string, format: :uri},
+              url: %Schema{type: :string, format: :uri, maxLength: 255},
               events: event_type(min_items: 1),
               enabled: %Schema{type: :boolean}
             },
@@ -161,7 +161,7 @@ defmodule Pleroma.Web.ApiSpec.Admin.WebhookOperation do
       type: :object,
       properties: %{
         id: %Schema{type: :string},
-        url: %Schema{type: :string, format: :uri},
+        url: %Schema{type: :string, format: :uri, maxLength: 255},
         events: event_type(),
         secret: %Schema{type: :string},
         enabled: %Schema{type: :boolean},

lib/pleroma/web/api_spec/operations/chat_operation.ex

@@ -31,7 +31,8 @@ defmodule Pleroma.Web.ApiSpec.ChatOperation do
             "The updated chat",
             "application/json",
             Chat
-          )
+          ),
+        404 => Operation.response("Not Found", "application/json", ApiError)
       },
       security: [
         %{
@@ -56,7 +57,8 @@ defmodule Pleroma.Web.ApiSpec.ChatOperation do
             "The read ChatMessage",
             "application/json",
             ChatMessage
-          )
+          ),
+        404 => Operation.response("Not Found", "application/json", ApiError)
       },
       security: [
         %{
@@ -87,7 +89,8 @@ defmodule Pleroma.Web.ApiSpec.ChatOperation do
             "The existing chat",
             "application/json",
             Chat
-          )
+          ),
+        404 => Operation.response("Not Found", "application/json", ApiError)
       },
       security: [
         %{
@@ -118,7 +121,8 @@ defmodule Pleroma.Web.ApiSpec.ChatOperation do
             "The created or existing chat",
             "application/json",
             Chat
-          )
+          ),
+        404 => Operation.response("Not Found", "application/json", ApiError)
       },
       security: [
         %{
@@ -146,7 +150,8 @@ defmodule Pleroma.Web.ApiSpec.ChatOperation do
         Operation.parameter(:pinned, :query, BooleanLike.schema(), "Include only pinned chats")
       ],
       responses: %{
-        200 => Operation.response("The chats of the user", "application/json", chats_response())
+        200 => Operation.response("The chats of the user", "application/json", chats_response()),
+        404 => Operation.response("Not Found", "application/json", ApiError)
       },
       security: [
         %{
@@ -172,7 +177,8 @@ defmodule Pleroma.Web.ApiSpec.ChatOperation do
         | pagination_params()
       ],
       responses: %{
-        200 => Operation.response("The chats of the user", "application/json", chats_response())
+        200 => Operation.response("The chats of the user", "application/json", chats_response()),
+        404 => Operation.response("Not Found", "application/json", ApiError)
       },
       security: [
         %{
@@ -224,6 +230,7 @@ defmodule Pleroma.Web.ApiSpec.ChatOperation do
             ChatMessage
           ),
         400 => Operation.response("Bad Request", "application/json", ApiError),
+        404 => Operation.response("Not Found", "application/json", ApiError),
         422 => Operation.response("MRF Rejection", "application/json", ApiError)
       },
       security: [
@@ -249,7 +256,8 @@ defmodule Pleroma.Web.ApiSpec.ChatOperation do
             "The deleted ChatMessage",
             "application/json",
             ChatMessage
-          )
+          ),
+        404 => Operation.response("Not Found", "application/json", ApiError)
       },
       security: [
         %{
@@ -268,7 +276,8 @@ defmodule Pleroma.Web.ApiSpec.ChatOperation do
         Operation.parameter(:id, :path, :string, "The id of the chat", required: true)
       ],
       responses: %{
-        200 => Operation.response("The existing chat", "application/json", Chat)
+        200 => Operation.response("The existing chat", "application/json", Chat),
+        404 => Operation.response("Not Found", "application/json", ApiError)
       },
       security: [
         %{
@@ -287,7 +296,8 @@ defmodule Pleroma.Web.ApiSpec.ChatOperation do
         Operation.parameter(:id, :path, :string, "The id of the chat", required: true)
       ],
       responses: %{
-        200 => Operation.response("The existing chat", "application/json", Chat)
+        200 => Operation.response("The existing chat", "application/json", Chat),
+        404 => Operation.response("Not Found", "application/json", ApiError)
       },
       security: [
         %{

lib/pleroma/web/api_spec/operations/list_operation.ex

@@ -41,7 +41,8 @@ defmodule Pleroma.Web.ApiSpec.ListOperation do
       responses: %{
         200 => Operation.response("List", "application/json", List),
         400 => Operation.response("Error", "application/json", ApiError),
-        404 => Operation.response("Error", "application/json", ApiError)
+        404 => Operation.response("Error", "application/json", ApiError),
+        422 => Operation.response("Error", "application/json", ApiError)
       }
     }
   end
@@ -175,7 +176,8 @@ defmodule Pleroma.Web.ApiSpec.ListOperation do
           exclusive: %Schema{
             type: :boolean,
             description: "Whether members of the list should be removed from the “Home” feed"
-          }
+          },
+          emoji: %Schema{type: :string, description: "List emoji", nullable: true}
         },
         required: [:title]
       },
@@ -194,7 +196,8 @@ defmodule Pleroma.Web.ApiSpec.ListOperation do
           exclusive: %Schema{
             type: :boolean,
             description: "Whether members of the list should be removed from the “Home” feed"
-          }
+          },
+          emoji: %Schema{type: :string, description: "List emoji", nullable: true}
         }
       },
       required: true

lib/pleroma/web/api_spec/operations/mastodon_admin/account_operation.ex

@@ -0,0 +1,348 @@
+# Pleroma: A lightweight social networking server
+# Copyright © 2017-2022 Pleroma Authors <https://pleroma.social/>
+# SPDX-License-Identifier: AGPL-3.0-only
+
+defmodule Pleroma.Web.ApiSpec.MastodonAdmin.AccountOperation do
+  alias OpenApiSpex.Operation
+  alias OpenApiSpex.Schema
+  alias Pleroma.Web.ApiSpec.Schemas.Account
+  alias Pleroma.Web.ApiSpec.Schemas.ApiError
+  alias Pleroma.Web.ApiSpec.Schemas.FlakeID
+
+  import Pleroma.Web.ApiSpec.Helpers
+
+  def open_api_operation(action) do
+    operation = String.to_existing_atom("#{action}_operation")
+    apply(__MODULE__, operation, [])
+  end
+
+  def index_operation do
+    %Operation{
+      tags: ["User administration (Mastodon API)"],
+      summary: "View accounts by criteria (v1)",
+      operationId: "MastodonAdmin.AccountController.index",
+      description: "View accounts matching certain criteria for filtering, up to 40 at a time.",
+      security: [%{"oAuth" => ["admin:read:accounts"]}],
+      parameters:
+        [
+          Operation.parameter(:local, :query, :boolean, "Filter for local accounts?"),
+          Operation.parameter(:remote, :query, :boolean, "Filter for remote accounts?"),
+          Operation.parameter(
+            :active,
+            :query,
+            :boolean,
+            "Filter for currently active accounts?"
+          ),
+          Operation.parameter(
+            :pending,
+            :query,
+            :boolean,
+            "Filter for currently pending accounts?"
+          ),
+          Operation.parameter(
+            :disabled,
+            :query,
+            :boolean,
+            "Filter for currently disabled accounts?"
+          ),
+          Operation.parameter(
+            :silenced,
+            :query,
+            :boolean,
+            "Filter for currently silenced accounts? (not implemented yet)"
+          ),
+          Operation.parameter(
+            :suspended,
+            :query,
+            :boolean,
+            "Filter for currently suspended accounts? (not implemented yet)"
+          ),
+          Operation.parameter(
+            :sensitized,
+            :query,
+            :boolean,
+            "Filter for accounts force-marked as sensitive? (not implemented yet)"
+          ),
+          Operation.parameter(:username, :query, :string, "Search for the given username"),
+          Operation.parameter(
+            :display_name,
+            :query,
+            :string,
+            "Search for the given display name"
+          ),
+          Operation.parameter(
+            :by_domain,
+            :query,
+            :string,
+            "Filter by the given domain"
+          ),
+          Operation.parameter(:email, :query, :string, "Lookup a user with this email"),
+          Operation.parameter(
+            :ip,
+            :query,
+            :string,
+            "Lookup users with this IP address (not implemented yet)"
+          ),
+          Operation.parameter(:staff, :query, :boolean, "Filter for staff accounts?")
+        ] ++
+          pagination_params(),
+      responses: %{
+        200 =>
+          Operation.response("Account", "application/json", %Schema{
+            title: "ArrayOfAccounts",
+            type: :array,
+            items: account()
+          }),
+        401 => Operation.response("Error", "application/json", ApiError)
+      }
+    }
+  end
+
+  def index2_operation do
+    %Operation{
+      tags: ["User administration (Mastodon API)"],
+      summary: "View accounts by criteria (v2)",
+      operationId: "MastodonAdmin.AccountController.index2",
+      description: "View accounts matching certain criteria for filtering, up to 40 at a time.",
+      security: [%{"oAuth" => ["admin:read:accounts"]}],
+      parameters:
+        [
+          Operation.parameter(
+            :origin,
+            :query,
+            %Schema{type: :string, enum: ["local", "remote"]},
+            "Filter for local or remote accounts"
+          ),
+          Operation.parameter(
+            :status,
+            :query,
+            %Schema{
+              type: :string,
+              enum: ["active", "inactive", "pending", "disabled", "silenced", "suspended"]
+            },
+            "Filter for active, pending, disabled, silenced or suspended accounts"
+          ),
+          Operation.parameter(
+            :permissions,
+            :query,
+            :string,
+            "Filter for accounts with staff permissions (users that can manage reports)."
+          ),
+          Operation.parameter(
+            :role_ids,
+            :query,
+            %Schema{
+              oneOf: [
+                %Schema{type: :array, items: %Schema{type: :string}},
+                %Schema{type: :string}
+              ]
+            },
+            "Filter for users with these roles. (not implemented yet)"
+          ),
+          Operation.parameter(
+            :invited_by,
+            :query,
+            :string,
+            "Lookup users invited by the account with this ID. (not implemented yet)"
+          ),
+          Operation.parameter(:username, :query, :string, "Search for the given username"),
+          Operation.parameter(
+            :display_name,
+            :query,
+            :string,
+            "Search for the given display name"
+          ),
+          Operation.parameter(
+            :by_domain,
+            :query,
+            :string,
+            "Filter by the given domain"
+          ),
+          Operation.parameter(:email, :query, :string, "Lookup a user with this email"),
+          Operation.parameter(
+            :ip,
+            :query,
+            :string,
+            "Lookup users with this IP address (not implemented yet)"
+          )
+        ] ++
+          pagination_params(),
+      responses: %{
+        200 =>
+          Operation.response("Account", "application/json", %Schema{
+            title: "ArrayOfAccounts",
+            type: :array,
+            items: account()
+          }),
+        401 => Operation.response("Error", "application/json", ApiError)
+      }
+    }
+  end
+
+  def show_operation do
+    %Operation{
+      tags: ["User administration (Mastodon API)"],
+      summary: "View a specific account",
+      operationId: "MastodonAdmin.AccountController.show",
+      description: "View admin-level information about the given account.",
+      security: [%{"oAuth" => ["admin:read:accounts"]}],
+      parameters: [
+        Operation.parameter(:id, :path, :string, "ID of the account")
+      ],
+      responses: %{
+        200 => Operation.response("Account", "application/json", account()),
+        401 => Operation.response("Error", "application/json", ApiError),
+        404 => Operation.response("Error", "application/json", ApiError)
+      }
+    }
+  end
+
+  def account_action_operation do
+    %Operation{
+      tags: ["User administration (Mastodon API)"],
+      summary: "Perform an action against an account",
+      operationId: "MastodonAdmin.AccountController.account_action",
+      description:
+        "Perform an action against an account and log this action in the moderation history.",
+      security: [%{"oAuth" => ["admin:write:accounts"]}],
+      parameters: [
+        Operation.parameter(:id, :path, :string, "ID of the account")
+      ],
+      requestBody:
+        request_body(
+          "Parameters",
+          %Schema{
+            type: :object,
+            properties: %{
+              type: %Schema{
+                type: :string,
+                enum: ["none", "disable"]
+              },
+              report_id: %Schema{
+                type: :string,
+                nullable: true,
+                description: "ID of an associated report that caused this action to be taken"
+              }
+            },
+            required: [:type]
+          },
+          required: true
+        ),
+      responses: %{
+        204 => no_content_response(),
+        400 => Operation.response("Error", "application/json", ApiError),
+        401 => Operation.response("Error", "application/json", ApiError),
+        403 => Operation.response("Error", "application/json", ApiError),
+        404 => Operation.response("Error", "application/json", ApiError)
+      }
+    }
+  end
+
+  def delete_operation do
+    %Operation{
+      tags: ["User administration (Mastodon API)"],
+      summary: "Delete a specific account",
+      operationId: "MastodonAdmin.AccountController.delete",
+      description: "Delete the given account.",
+      security: [%{"oAuth" => ["admin:write:accounts"]}],
+      parameters: [
+        Operation.parameter(:id, :path, :string, "ID of the account")
+      ],
+      responses: %{
+        200 => Operation.response("Account", "application/json", account()),
+        401 => Operation.response("Error", "application/json", ApiError),
+        404 => Operation.response("Error", "application/json", ApiError)
+      }
+    }
+  end
+
+  def enable_operation do
+    %Operation{
+      tags: ["User administration (Mastodon API)"],
+      summary: "Re-enable account",
+      operationId: "MastodonAdmin.AccountController.enable",
+      description: "Re-enable a local account whose login is currently disabled.",
+      security: [%{"oAuth" => ["admin:write:accounts"]}],
+      parameters: [
+        Operation.parameter(:id, :path, :string, "ID of the account")
+      ],
+      responses: %{
+        200 => Operation.response("Account", "application/json", account()),
+        401 => Operation.response("Error", "application/json", ApiError),
+        404 => Operation.response("Error", "application/json", ApiError)
+      }
+    }
+  end
+
+  def approve_operation do
+    %Operation{
+      tags: ["User administration (Mastodon API)"],
+      summary: "Approve pending account",
+      operationId: "MastodonAdmin.AccountController.approve",
+      description: "Approve the given local account if it is currently pending approval.",
+      parameters: [
+        Operation.parameter(:id, :path, :string, "ID of the account")
+      ],
+      responses: %{
+        200 => Operation.response("Account", "application/json", account()),
+        401 => Operation.response("Error", "application/json", ApiError),
+        404 => Operation.response("Error", "application/json", ApiError)
+      }
+    }
+  end
+
+  def reject_operation do
+    %Operation{
+      tags: ["User administration (Mastodon API)"],
+      summary: "Reject pending account",
+      operationId: "MastodonAdmin.AccountController.reject",
+      description: "Reject the given local account if it is currently pending approval.",
+      parameters: [
+        Operation.parameter(:id, :path, :string, "ID of the account")
+      ],
+      responses: %{
+        200 => Operation.response("Account", "application/json", account()),
+        400 => Operation.response("Error", "application/json", ApiError),
+        401 => Operation.response("Error", "application/json", ApiError),
+        404 => Operation.response("Error", "application/json", ApiError)
+      }
+    }
+  end
+
+  def account do
+    %Schema{
+      title: "Admin::Account",
+      description: "Admin-level information about a given account.",
+      type: :object,
+      properties: %{
+        id: FlakeID,
+        username: %Schema{type: :string},
+        domain: %Schema{type: :string, nullable: true},
+        created_at: %Schema{type: :string, format: "date-time"},
+        email: %Schema{type: :string, format: "email", nullable: true},
+        ip: %Schema{type: :string, nullable: true},
+        ips: %Schema{
+          type: :array,
+          items: %Schema{
+            type: :object,
+            properties: %{
+              ip: %Schema{type: :string},
+              used_at: %Schema{type: :string, format: "date-time"}
+            }
+          }
+        },
+        locale: %Schema{type: :string, nullable: true},
+        invite_request: %Schema{type: :string, nullable: true},
+        role: %Schema{type: :string, nullable: true},
+        confirmed: %Schema{type: :boolean},
+        approved: %Schema{type: :boolean},
+        disabled: %Schema{type: :boolean},
+        silenced: %Schema{type: :boolean, nullable: true},
+        suspended: %Schema{type: :boolean, nullable: true},
+        account: Account,
+        created_by_application_id: %Schema{type: :string, nullable: true},
+        invited_by_account_id: %Schema{type: :string, nullable: true}
+      }
+    }
+  end
+end

lib/pleroma/web/api_spec/operations/mastodon_admin/report_operation.ex

@@ -0,0 +1,180 @@
+# Pleroma: A lightweight social networking server
+# Copyright © 2017-2022 Pleroma Authors <https://pleroma.social/>
+# SPDX-License-Identifier: AGPL-3.0-only
+
+defmodule Pleroma.Web.ApiSpec.MastodonAdmin.ReportOperation do
+  alias OpenApiSpex.Operation
+  alias OpenApiSpex.Schema
+  alias Pleroma.Web.ApiSpec.MastodonAdmin.AccountOperation
+  alias Pleroma.Web.ApiSpec.Schemas.ApiError
+  alias Pleroma.Web.ApiSpec.Schemas.FlakeID
+  alias Pleroma.Web.ApiSpec.Schemas.Status
+
+  import Pleroma.Web.ApiSpec.Helpers
+
+  def open_api_operation(action) do
+    operation = String.to_existing_atom("#{action}_operation")
+    apply(__MODULE__, operation, [])
+  end
+
+  def index_operation do
+    %Operation{
+      tags: ["Report management (Mastodon API)"],
+      summary: "View all reports",
+      operationId: "MastodonAdmin.ReportController.index",
+      description:
+        "View all reports. Pagination may be done with HTTP Link header in the response.",
+      security: [%{"oAuth" => ["admin:read:reports"]}],
+      parameters:
+        [
+          Operation.parameter(:resolved, :query, :boolean, "Filter for resolved reports"),
+          Operation.parameter(:unresolved, :query, :boolean, "Filter for open reports"),
+          Operation.parameter(:account_id, :query, :string, "Filter by author account id"),
+          Operation.parameter(
+            :target_account_id,
+            :query,
+            :string,
+            "Filter by report target account id"
+          )
+        ] ++
+          pagination_params(),
+      responses: %{
+        200 =>
+          Operation.response("Reports", "application/json", %Schema{
+            title: "ArrayOfReports",
+            type: :array,
+            items: report()
+          }),
+        401 => Operation.response("Error", "application/json", ApiError)
+      }
+    }
+  end
+
+  def show_operation do
+    %Operation{
+      tags: ["Report management (Mastodon API)"],
+      summary: "View a single report",
+      operationId: "MastodonAdmin.ReportController.show",
+      description: "View information about the report with the given ID.",
+      security: [%{"oAuth" => ["admin:read:reports"]}],
+      parameters: [
+        Operation.parameter(:id, :path, :string, "ID of the report")
+      ],
+      responses: %{
+        200 => Operation.response("Report", "application/json", report()),
+        401 => Operation.response("Error", "application/json", ApiError),
+        404 => Operation.response("Error", "application/json", ApiError)
+      }
+    }
+  end
+
+  def resolve_operation do
+    %Operation{
+      tags: ["Report management (Mastodon API)"],
+      summary: "Mark as resolved",
+      operationId: "MastodonAdmin.ReportController.resolve",
+      description: "Mark a report as resolved with no further action taken.",
+      security: [%{"oAuth" => ["admin:write:reports"]}],
+      parameters: [
+        Operation.parameter(:id, :path, :string, "ID of the report")
+      ],
+      responses: %{
+        200 => Operation.response("Report", "application/json", report()),
+        400 => Operation.response("Error", "application/json", ApiError),
+        401 => Operation.response("Error", "application/json", ApiError),
+        404 => Operation.response("Error", "application/json", ApiError)
+      }
+    }
+  end
+
+  def reopen_operation do
+    %Operation{
+      tags: ["Report management (Mastodon API)"],
+      summary: "Re-open report",
+      operationId: "MastodonAdmin.ReportController.reopen",
+      description: "Reopen a currently closed report.",
+      security: [%{"oAuth" => ["admin:write:reports"]}],
+      parameters: [
+        Operation.parameter(:id, :path, :string, "ID of the report")
+      ],
+      responses: %{
+        200 => Operation.response("Report", "application/json", report()),
+        400 => Operation.response("Error", "application/json", ApiError),
+        401 => Operation.response("Error", "application/json", ApiError),
+        404 => Operation.response("Error", "application/json", ApiError)
+      }
+    }
+  end
+
+  def assign_to_self_operation do
+    %Operation{
+      tags: ["Report management (Mastodon API)"],
+      summary: "Assign report to self",
+      operationId: "MastodonAdmin.ReportController.assign_to_self",
+      security: [%{"oAuth" => ["admin:write:reports"]}],
+      parameters: [Operation.parameter(:id, :path, :string, "ID of the report")],
+      responses: report_update_responses()
+    }
+  end
+
+  def unassign_operation do
+    %Operation{
+      tags: ["Report management (Mastodon API)"],
+      summary: "Unassign report",
+      operationId: "MastodonAdmin.ReportController.unassign",
+      security: [%{"oAuth" => ["admin:write:reports"]}],
+      parameters: [Operation.parameter(:id, :path, :string, "ID of the report")],
+      responses: report_update_responses()
+    }
+  end
+
+  defp report_update_responses do
+    %{
+      200 => Operation.response("Report", "application/json", report()),
+      400 => Operation.response("Error", "application/json", ApiError),
+      401 => Operation.response("Error", "application/json", ApiError),
+      404 => Operation.response("Error", "application/json", ApiError)
+    }
+  end
+
+  defp report do
+    %Schema{
+      title: "Admin::Report",
+      type: :object,
+      properties: %{
+        id: FlakeID,
+        action_taken: %Schema{type: :boolean},
+        action_taken_at: %Schema{type: :string, format: "date-time", nullable: true},
+        category: %Schema{type: :string, enum: ["spam", "legal", "violation", "other"]},
+        comment: %Schema{type: :string, nullable: true},
+        forwarded: %Schema{type: :boolean, nullable: true},
+        created_at: %Schema{type: :string, format: "date-time"},
+        updated_at: %Schema{type: :string, format: "date-time"},
+        account: AccountOperation.account(),
+        target_account: AccountOperation.account(),
+        assigned_account: %Schema{
+          oneOf: [AccountOperation.account()],
+          nullable: true
+        },
+        action_taken_by_account: %Schema{
+          oneOf: [AccountOperation.account()],
+          nullable: true
+        },
+        statuses: %Schema{
+          type: :array,
+          items: Status
+        },
+        rules: %Schema{
+          type: :array,
+          items: %Schema{
+            type: :object,
+            properties: %{
+              id: %Schema{type: :string},
+              text: %Schema{type: :string}
+            }
+          }
+        }
+      }
+    }
+  end
+end

lib/pleroma/web/api_spec/operations/notification_operation.ex

@@ -90,6 +90,79 @@ defmodule Pleroma.Web.ApiSpec.NotificationOperation do
     }
   end
 
+  def grouped_index_operation do
+    %Operation{
+      tags: ["Notifications"],
+      summary: "Retrieve grouped notifications",
+      description: "Notifications concerning the user, grouped by supported notification types.",
+      operationId: "NotificationController.grouped_index",
+      security: [%{"oAuth" => ["read:notifications"]}],
+      parameters: grouped_notification_params() ++ pagination_params(),
+      responses: %{
+        200 => Operation.response("Grouped notifications", "application/json", grouped_result()),
+        404 => Operation.response("Error", "application/json", ApiError)
+      }
+    }
+  end
+
+  def show_group_operation do
+    %Operation{
+      tags: ["Notifications"],
+      summary: "Retrieve a notification group",
+      operationId: "NotificationController.show_group",
+      security: [%{"oAuth" => ["read:notifications"]}],
+      parameters: [group_key_param()],
+      responses: %{
+        200 => Operation.response("Grouped notifications", "application/json", grouped_result()),
+        404 => Operation.response("Error", "application/json", ApiError)
+      }
+    }
+  end
+
+  def group_accounts_operation do
+    %Operation{
+      tags: ["Notifications"],
+      summary: "Retrieve notification group accounts",
+      operationId: "NotificationController.group_accounts",
+      security: [%{"oAuth" => ["read:notifications"]}],
+      parameters: [group_key_param()],
+      responses: %{
+        200 =>
+          Operation.response("Accounts", "application/json", %Schema{
+            type: :array,
+            items: Account
+          })
+      }
+    }
+  end
+
+  def unread_count_operation do
+    %Operation{
+      tags: ["Notifications"],
+      summary: "Retrieve unread grouped notification count",
+      operationId: "NotificationController.unread_count",
+      security: [%{"oAuth" => ["read:notifications"]}],
+      parameters:
+        grouped_notification_params() ++
+          [
+            Operation.parameter(
+              :limit,
+              :query,
+              %Schema{type: :integer},
+              "Maximum number of notifications to count"
+            )
+          ],
+      responses: %{
+        200 =>
+          Operation.response("Unread notification group count", "application/json", %Schema{
+            type: :object,
+            properties: %{count: %Schema{type: :integer}}
+          }),
+        404 => Operation.response("Error", "application/json", ApiError)
+      }
+    }
+  end
+
   def clear_operation do
     %Operation{
       tags: ["Notifications"],
@@ -113,6 +186,18 @@ defmodule Pleroma.Web.ApiSpec.NotificationOperation do
     }
   end
 
+  def dismiss_group_operation do
+    %Operation{
+      tags: ["Notifications"],
+      summary: "Dismiss a notification group",
+      description: "Clear all notifications in a notification group from the server.",
+      operationId: "NotificationController.dismiss_group",
+      parameters: [group_key_param()],
+      security: [%{"oAuth" => ["write:notifications"]}],
+      responses: %{200 => empty_object_response()}
+    }
+  end
+
   def dismiss_via_body_operation do
     %Operation{
       tags: ["Notifications"],
@@ -183,7 +268,7 @@ defmodule Pleroma.Web.ApiSpec.NotificationOperation do
       },
       example: %{
         "id" => "34975861",
-        "group-key" => "ungrouped-34975861",
+        "group_key" => "ungrouped-34975861",
         "type" => "mention",
         "created_at" => "2019-11-23T07:49:02.064Z",
         "account" => Account.schema().example,
@@ -193,6 +278,73 @@ defmodule Pleroma.Web.ApiSpec.NotificationOperation do
     }
   end
 
+  defp grouped_result do
+    %Schema{
+      title: "GroupedNotificationsResults",
+      type: :object,
+      properties: %{
+        accounts: %Schema{type: :array, items: Account},
+        statuses: %Schema{type: :array, items: Status},
+        notification_groups: %Schema{type: :array, items: notification_group()}
+      },
+      required: [:accounts, :statuses, :notification_groups]
+    }
+  end
+
+  defp notification_group do
+    %Schema{
+      title: "NotificationGroup",
+      type: :object,
+      properties: %{
+        group_key: %Schema{type: :string},
+        notifications_count: %Schema{type: :integer},
+        type: notification_type(),
+        most_recent_notification_id: %Schema{type: :string},
+        page_min_id: %Schema{type: :string, nullable: true},
+        page_max_id: %Schema{type: :string, nullable: true},
+        latest_page_notification_at: %Schema{type: :string, format: :"date-time", nullable: true},
+        sample_account_ids: %Schema{type: :array, items: %Schema{type: :string}},
+        status_id: %Schema{type: :string, nullable: true}
+      },
+      required: [
+        :group_key,
+        :notifications_count,
+        :type,
+        :most_recent_notification_id,
+        :sample_account_ids
+      ]
+    }
+  end
+
+  defp grouped_notification_params do
+    [
+      Operation.parameter(
+        :exclude_types,
+        :query,
+        %Schema{type: :array, items: notification_type()},
+        "Array of types to exclude"
+      ),
+      Operation.parameter(
+        :account_id,
+        :query,
+        %Schema{type: :string},
+        "Return only notifications received from this account"
+      ),
+      Operation.parameter(
+        :types,
+        :query,
+        %Schema{type: :array, items: notification_type()},
+        "Include the notifications for activities with the given types"
+      ),
+      Operation.parameter(
+        :grouped_types,
+        :query,
+        %Schema{type: :array, items: notification_type()},
+        "Notification types that may be grouped"
+      )
+    ]
+  end
+
   defp notification_type do
     %Schema{
       type: :string,
@@ -238,4 +390,11 @@ defmodule Pleroma.Web.ApiSpec.NotificationOperation do
       required: true
     )
   end
+
+  defp group_key_param do
+    Operation.parameter(:group_key, :path, :string, "Notification group key",
+      example: "favourite-123",
+      required: true
+    )
+  end
 end

lib/pleroma/web/api_spec/operations/status_operation.ex

@@ -356,34 +356,6 @@ defmodule Pleroma.Web.ApiSpec.StatusOperation do
     }
   end
 
-  def card_operation do
-    %Operation{
-      tags: ["Retrieve status information"],
-      deprecated: true,
-      summary: "Preview card",
-      description: "Deprecated in favor of card property inlined on Status entity",
-      operationId: "StatusController.card",
-      parameters: [id_param()],
-      security: [%{"oAuth" => ["read:statuses"]}],
-      responses: %{
-        200 =>
-          Operation.response("Card", "application/json", %Schema{
-            type: :object,
-            nullable: true,
-            properties: %{
-              type: %Schema{type: :string, enum: ["link", "photo", "video", "rich"]},
-              provider_name: %Schema{type: :string, nullable: true},
-              provider_url: %Schema{type: :string, format: :uri},
-              url: %Schema{type: :string, format: :uri},
-              image: %Schema{type: :string, nullable: true, format: :uri},
-              title: %Schema{type: :string},
-              description: %Schema{type: :string}
-            }
-          })
-      }
-    }
-  end
-
   def favourited_by_operation do
     %Operation{
       tags: ["Retrieve status information"],

lib/pleroma/web/api_spec/schemas/chat_message.ex

@@ -5,6 +5,7 @@
 defmodule Pleroma.Web.ApiSpec.Schemas.ChatMessage do
   alias OpenApiSpex.Schema
   alias Pleroma.Web.ApiSpec.Schemas.Emoji
+  alias Pleroma.Web.ApiSpec.Schemas.PreviewCard
 
   require OpenApiSpex
 
@@ -22,36 +23,8 @@ defmodule Pleroma.Web.ApiSpec.Schemas.ChatMessage do
       emojis: %Schema{type: :array, items: Emoji},
       attachment: %Schema{type: :object, nullable: true},
       card: %Schema{
-        type: :object,
-        nullable: true,
-        description: "Preview card for links included within status content",
-        required: [:url, :title, :description, :type],
-        properties: %{
-          type: %Schema{
-            type: :string,
-            enum: ["link", "photo", "video", "rich"],
-            description: "The type of the preview card"
-          },
-          provider_name: %Schema{
-            type: :string,
-            nullable: true,
-            description: "The provider of the original resource"
-          },
-          provider_url: %Schema{
-            type: :string,
-            format: :uri,
-            description: "A link to the provider of the original resource"
-          },
-          url: %Schema{type: :string, format: :uri, description: "Location of linked resource"},
-          image: %Schema{
-            type: :string,
-            nullable: true,
-            format: :uri,
-            description: "Preview thumbnail"
-          },
-          title: %Schema{type: :string, description: "Title of linked resource"},
-          description: %Schema{type: :string, description: "Description of preview"}
-        }
+        allOf: [PreviewCard],
+        nullable: true
       },
       unread: %Schema{type: :boolean, description: "Whether a message has been marked as read."}
     },

lib/pleroma/web/api_spec/schemas/list.ex

@@ -17,11 +17,26 @@ defmodule Pleroma.Web.ApiSpec.Schemas.List do
       exclusive: %Schema{
         type: :boolean,
         description: "Whether members of the list should be removed from the “Home” feed"
+      },
+      pleroma: %Schema{
+        type: :object,
+        properties: %{
+          emoji: %Schema{type: :string, description: "List emoji", nullable: true},
+          emoji_url: %Schema{
+            type: :string,
+            description: "URL of the list emoji if it's a custom emoji, null otherwise",
+            nullable: true
+          }
+        }
       }
     },
     example: %{
       "id" => "12249",
-      "title" => "Friends"
+      "title" => "Friends",
+      "pleroma" => %{
+        "emoji" => nil,
+        "emoji_url" => nil
+      }
     }
   })
 end

lib/pleroma/web/api_spec/schemas/preview_card.ex

@@ -0,0 +1,109 @@
+# Pleroma: A lightweight social networking server
+# Copyright © 2017-2022 Pleroma Authors <https://pleroma.social/>
+# SPDX-License-Identifier: AGPL-3.0-only
+
+defmodule Pleroma.Web.ApiSpec.Schemas.PreviewCard do
+  alias OpenApiSpex.Schema
+  alias Pleroma.Web.ApiSpec.Schemas.Account
+
+  require OpenApiSpex
+
+  OpenApiSpex.schema(%{
+    title: "PreviewCard",
+    description: "Preview card for a link included within status or chat message content",
+    type: :object,
+    required: [
+      :url,
+      :title,
+      :description,
+      :language,
+      :type,
+      :authors,
+      :author_name,
+      :author_url,
+      :provider_name,
+      :provider_url,
+      :html,
+      :width,
+      :height,
+      :image,
+      :image_description,
+      :embed_url,
+      :blurhash,
+      :published_at
+    ],
+    properties: %{
+      url: %Schema{type: :string, format: :uri, description: "Location of linked resource"},
+      title: %Schema{type: :string, description: "Title of linked resource"},
+      description: %Schema{type: :string, description: "Description of preview"},
+      language: %Schema{
+        type: :string,
+        nullable: true,
+        description: "Language of the linked resource"
+      },
+      type: %Schema{
+        type: :string,
+        enum: ["link", "photo", "video", "rich"],
+        description: "The type of the preview card"
+      },
+      authors: %Schema{
+        type: :array,
+        description: "Fediverse accounts of the authors of the original resource",
+        items: %Schema{
+          type: :object,
+          required: [:name, :url, :account],
+          properties: %{
+            name: %Schema{type: :string},
+            url: %Schema{type: :string},
+            account: %Schema{allOf: [Account], nullable: true}
+          }
+        }
+      },
+      author_name: %Schema{type: :string, description: "Author of the original resource"},
+      author_url: %Schema{
+        type: :string,
+        description: "Link to the author of the original resource"
+      },
+      provider_name: %Schema{
+        type: :string,
+        description: "The provider of the original resource"
+      },
+      provider_url: %Schema{
+        type: :string,
+        description: "A link to the provider of the original resource"
+      },
+      html: %Schema{
+        type: :string,
+        format: :html,
+        description: "HTML to be used for generating the preview card"
+      },
+      width: %Schema{type: :integer, description: "Width of preview, in pixels"},
+      height: %Schema{type: :integer, description: "Height of preview, in pixels"},
+      image: %Schema{
+        type: :string,
+        nullable: true,
+        format: :uri,
+        description: "Preview thumbnail"
+      },
+      image_description: %Schema{
+        type: :string,
+        description: "Alternate text that describes what is in the thumbnail"
+      },
+      embed_url: %Schema{
+        type: :string,
+        description: "Used for photo embeds, instead of custom `html`"
+      },
+      blurhash: %Schema{
+        type: :string,
+        nullable: true,
+        description:
+          "A hash computed by the [BlurHash algorithm](https://github.com/woltapp/blurhash), for generating colorful preview thumbnails when media has not been downloaded yet."
+      },
+      published_at: %Schema{
+        type: :string,
+        nullable: true,
+        description: "Publication date of the linked resource"
+      }
+    }
+  })
+end

lib/pleroma/web/api_spec/schemas/status.ex

@@ -9,6 +9,7 @@ defmodule Pleroma.Web.ApiSpec.Schemas.Status do
   alias Pleroma.Web.ApiSpec.Schemas.Emoji
   alias Pleroma.Web.ApiSpec.Schemas.FlakeID
   alias Pleroma.Web.ApiSpec.Schemas.Poll
+  alias Pleroma.Web.ApiSpec.Schemas.PreviewCard
   alias Pleroma.Web.ApiSpec.Schemas.Tag
   alias Pleroma.Web.ApiSpec.Schemas.VisibilityScope
 
@@ -31,40 +32,8 @@ defmodule Pleroma.Web.ApiSpec.Schemas.Status do
       },
       bookmarked: %Schema{type: :boolean, description: "Have you bookmarked this status?"},
       card: %Schema{
-        type: :object,
-        nullable: true,
-        description: "Preview card for links included within status content",
-        required: [:url, :title, :description, :type],
-        properties: %{
-          type: %Schema{
-            type: :string,
-            enum: ["link", "photo", "video", "rich"],
-            description: "The type of the preview card"
-          },
-          provider_name: %Schema{
-            type: :string,
-            nullable: true,
-            description: "The provider of the original resource"
-          },
-          provider_url: %Schema{
-            type: :string,
-            format: :uri,
-            description: "A link to the provider of the original resource"
-          },
-          url: %Schema{type: :string, format: :uri, description: "Location of linked resource"},
-          image: %Schema{
-            type: :string,
-            nullable: true,
-            format: :uri,
-            description: "Preview thumbnail"
-          },
-          image_description: %Schema{
-            type: :string,
-            description: "Alternate text that describes what is in the thumbnail"
-          },
-          title: %Schema{type: :string, description: "Title of linked resource"},
-          description: %Schema{type: :string, description: "Description of preview"}
-        }
+        allOf: [PreviewCard],
+        nullable: true
       },
       content: %Schema{type: :string, format: :html, description: "HTML-encoded status content"},
       text: %Schema{