First

1 files changed, 791 insertions, 0 deletions

diff --git a/lib/pleroma/web/api_spec/operations/status_operation.ex b/lib/pleroma/web/api_spec/operations/status_operation.ex
new file mode 100644
index 0000000..e921128
--- /dev/null
+++ b/lib/pleroma/web/api_spec/operations/status_operation.ex
@@ -0,0 +1,791 @@
+# 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.StatusOperation do
+  alias OpenApiSpex.Operation
+  alias OpenApiSpex.Schema
+  alias Pleroma.Web.ApiSpec.AccountOperation
+  alias Pleroma.Web.ApiSpec.Schemas.Account
+  alias Pleroma.Web.ApiSpec.Schemas.ApiError
+  alias Pleroma.Web.ApiSpec.Schemas.Attachment
+  alias Pleroma.Web.ApiSpec.Schemas.BooleanLike
+  alias Pleroma.Web.ApiSpec.Schemas.Emoji
+  alias Pleroma.Web.ApiSpec.Schemas.FlakeID
+  alias Pleroma.Web.ApiSpec.Schemas.Poll
+  alias Pleroma.Web.ApiSpec.Schemas.ScheduledStatus
+  alias Pleroma.Web.ApiSpec.Schemas.Status
+  alias Pleroma.Web.ApiSpec.Schemas.VisibilityScope
+
+  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: ["Retrieve status information"],
+      summary: "Multiple statuses",
+      security: [%{"oAuth" => ["read:statuses"]}],
+      parameters: [
+        Operation.parameter(
+          :ids,
+          :query,
+          %Schema{type: :array, items: FlakeID},
+          "Array of status IDs"
+        ),
+        Operation.parameter(
+          :with_muted,
+          :query,
+          BooleanLike,
+          "Include reactions from muted acccounts."
+        )
+      ],
+      operationId: "StatusController.index",
+      responses: %{
+        200 => Operation.response("Array of Status", "application/json", array_of_statuses())
+      }
+    }
+  end
+
+  def create_operation do
+    %Operation{
+      tags: ["Status actions"],
+      summary: "Publish new status",
+      security: [%{"oAuth" => ["write:statuses"]}],
+      description: "Post a new status",
+      operationId: "StatusController.create",
+      requestBody: request_body("Parameters", create_request(), required: true),
+      responses: %{
+        200 =>
+          Operation.response(
+            "Status. When `scheduled_at` is present, ScheduledStatus is returned instead",
+            "application/json",
+            %Schema{anyOf: [Status, ScheduledStatus]}
+          ),
+        422 => Operation.response("Bad Request / MRF Rejection", "application/json", ApiError)
+      }
+    }
+  end
+
+  def show_operation do
+    %Operation{
+      tags: ["Retrieve status information"],
+      summary: "Status",
+      description: "View information about a status",
+      operationId: "StatusController.show",
+      security: [%{"oAuth" => ["read:statuses"]}],
+      parameters: [
+        id_param(),
+        Operation.parameter(
+          :with_muted,
+          :query,
+          BooleanLike,
+          "Include reactions from muted acccounts."
+        )
+      ],
+      responses: %{
+        200 => status_response(),
+        404 => Operation.response("Not Found", "application/json", ApiError)
+      }
+    }
+  end
+
+  def delete_operation do
+    %Operation{
+      tags: ["Status actions"],
+      summary: "Delete",
+      security: [%{"oAuth" => ["write:statuses"]}],
+      description: "Delete one of your own statuses",
+      operationId: "StatusController.delete",
+      parameters: [id_param()],
+      responses: %{
+        200 => status_response(),
+        403 => Operation.response("Forbidden", "application/json", ApiError),
+        404 => Operation.response("Not Found", "application/json", ApiError)
+      }
+    }
+  end
+
+  def reblog_operation do
+    %Operation{
+      tags: ["Status actions"],
+      summary: "Reblog",
+      security: [%{"oAuth" => ["write:statuses"]}],
+      description: "Share a status",
+      operationId: "StatusController.reblog",
+      parameters: [id_param()],
+      requestBody:
+        request_body("Parameters", %Schema{
+          type: :object,
+          properties: %{
+            visibility: %Schema{allOf: [VisibilityScope]}
+          }
+        }),
+      responses: %{
+        200 => status_response(),
+        404 => Operation.response("Not Found", "application/json", ApiError)
+      }
+    }
+  end
+
+  def unreblog_operation do
+    %Operation{
+      tags: ["Status actions"],
+      summary: "Undo reblog",
+      security: [%{"oAuth" => ["write:statuses"]}],
+      description: "Undo a reshare of a status",
+      operationId: "StatusController.unreblog",
+      parameters: [id_param()],
+      responses: %{
+        200 => status_response(),
+        404 => Operation.response("Not Found", "application/json", ApiError)
+      }
+    }
+  end
+
+  def favourite_operation do
+    %Operation{
+      tags: ["Status actions"],
+      summary: "Favourite",
+      security: [%{"oAuth" => ["write:favourites"]}],
+      description: "Add a status to your favourites list",
+      operationId: "StatusController.favourite",
+      parameters: [id_param()],
+      responses: %{
+        200 => status_response(),
+        404 => Operation.response("Not Found", "application/json", ApiError)
+      }
+    }
+  end
+
+  def unfavourite_operation do
+    %Operation{
+      tags: ["Status actions"],
+      summary: "Undo favourite",
+      security: [%{"oAuth" => ["write:favourites"]}],
+      description: "Remove a status from your favourites list",
+      operationId: "StatusController.unfavourite",
+      parameters: [id_param()],
+      responses: %{
+        200 => status_response(),
+        404 => Operation.response("Not Found", "application/json", ApiError)
+      }
+    }
+  end
+
+  def pin_operation do
+    %Operation{
+      tags: ["Status actions"],
+      summary: "Pin to profile",
+      security: [%{"oAuth" => ["write:accounts"]}],
+      description: "Feature one of your own public statuses at the top of your profile",
+      operationId: "StatusController.pin",
+      parameters: [id_param()],
+      responses: %{
+        200 => status_response(),
+        400 =>
+          Operation.response("Bad Request", "application/json", %Schema{
+            allOf: [ApiError],
+            title: "Unprocessable Entity",
+            example: %{
+              "error" => "You have already pinned the maximum number of statuses"
+            }
+          }),
+        404 =>
+          Operation.response("Not found", "application/json", %Schema{
+            allOf: [ApiError],
+            title: "Unprocessable Entity",
+            example: %{
+              "error" => "Record not found"
+            }
+          }),
+        422 =>
+          Operation.response(
+            "Unprocessable Entity",
+            "application/json",
+            %Schema{
+              allOf: [ApiError],
+              title: "Unprocessable Entity",
+              example: %{
+                "error" => "Someone else's status cannot be pinned"
+              }
+            }
+          )
+      }
+    }
+  end
+
+  def unpin_operation do
+    %Operation{
+      tags: ["Status actions"],
+      summary: "Unpin from profile",
+      security: [%{"oAuth" => ["write:accounts"]}],
+      description: "Unfeature a status from the top of your profile",
+      operationId: "StatusController.unpin",
+      parameters: [id_param()],
+      responses: %{
+        200 => status_response(),
+        400 =>
+          Operation.response("Bad Request", "application/json", %Schema{
+            allOf: [ApiError],
+            title: "Unprocessable Entity",
+            example: %{
+              "error" => "You have already pinned the maximum number of statuses"
+            }
+          }),
+        404 =>
+          Operation.response("Not found", "application/json", %Schema{
+            allOf: [ApiError],
+            title: "Unprocessable Entity",
+            example: %{
+              "error" => "Record not found"
+            }
+          })
+      }
+    }
+  end
+
+  def bookmark_operation do
+    %Operation{
+      tags: ["Status actions"],
+      summary: "Bookmark",
+      security: [%{"oAuth" => ["write:bookmarks"]}],
+      description: "Privately bookmark a status",
+      operationId: "StatusController.bookmark",
+      parameters: [id_param()],
+      responses: %{
+        200 => status_response()
+      }
+    }
+  end
+
+  def unbookmark_operation do
+    %Operation{
+      tags: ["Status actions"],
+      summary: "Undo bookmark",
+      security: [%{"oAuth" => ["write:bookmarks"]}],
+      description: "Remove a status from your private bookmarks",
+      operationId: "StatusController.unbookmark",
+      parameters: [id_param()],
+      responses: %{
+        200 => status_response()
+      }
+    }
+  end
+
+  def mute_conversation_operation do
+    %Operation{
+      tags: ["Status actions"],
+      summary: "Mute conversation",
+      security: [%{"oAuth" => ["write:mutes"]}],
+      description: "Do not receive notifications for the thread that this status is part of.",
+      operationId: "StatusController.mute_conversation",
+      requestBody:
+        request_body("Parameters", %Schema{
+          type: :object,
+          properties: %{
+            expires_in: %Schema{
+              type: :integer,
+              nullable: true,
+              description: "Expire the mute in `expires_in` seconds. Default 0 for infinity",
+              default: 0
+            }
+          }
+        }),
+      parameters: [
+        id_param(),
+        Operation.parameter(
+          :expires_in,
+          :query,
+          %Schema{type: :integer, default: 0},
+          "Expire the mute in `expires_in` seconds. Default 0 for infinity"
+        )
+      ],
+      responses: %{
+        200 => status_response(),
+        400 => Operation.response("Error", "application/json", ApiError)
+      }
+    }
+  end
+
+  def unmute_conversation_operation do
+    %Operation{
+      tags: ["Status actions"],
+      summary: "Unmute conversation",
+      security: [%{"oAuth" => ["write:mutes"]}],
+      description:
+        "Start receiving notifications again for the thread that this status is part of",
+      operationId: "StatusController.unmute_conversation",
+      parameters: [id_param()],
+      responses: %{
+        200 => status_response(),
+        400 => Operation.response("Error", "application/json", ApiError)
+      }
+    }
+  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"],
+      summary: "Favourited by",
+      description: "View who favourited a given status",
+      operationId: "StatusController.favourited_by",
+      security: [%{"oAuth" => ["read:accounts"]}],
+      parameters: [id_param()],
+      responses: %{
+        200 =>
+          Operation.response(
+            "Array of Accounts",
+            "application/json",
+            AccountOperation.array_of_accounts()
+          ),
+        404 => Operation.response("Not Found", "application/json", ApiError)
+      }
+    }
+  end
+
+  def reblogged_by_operation do
+    %Operation{
+      tags: ["Retrieve status information"],
+      summary: "Reblogged by",
+      description: "View who reblogged a given status",
+      operationId: "StatusController.reblogged_by",
+      security: [%{"oAuth" => ["read:accounts"]}],
+      parameters: [id_param()],
+      responses: %{
+        200 =>
+          Operation.response(
+            "Array of Accounts",
+            "application/json",
+            AccountOperation.array_of_accounts()
+          ),
+        404 => Operation.response("Not Found", "application/json", ApiError)
+      }
+    }
+  end
+
+  def context_operation do
+    %Operation{
+      tags: ["Retrieve status information"],
+      summary: "Parent and child statuses",
+      description: "View statuses above and below this status in the thread",
+      operationId: "StatusController.context",
+      security: [%{"oAuth" => ["read:statuses"]}],
+      parameters: [id_param()],
+      responses: %{
+        200 => Operation.response("Context", "application/json", context())
+      }
+    }
+  end
+
+  def favourites_operation do
+    %Operation{
+      tags: ["Timelines"],
+      summary: "Favourited statuses",
+      description:
+        "Statuses the user has favourited. Please note that you have to use the link headers to paginate this. You can not build the query parameters yourself.",
+      operationId: "StatusController.favourites",
+      parameters: pagination_params(),
+      security: [%{"oAuth" => ["read:favourites"]}],
+      responses: %{
+        200 => Operation.response("Array of Statuses", "application/json", array_of_statuses())
+      }
+    }
+  end
+
+  def bookmarks_operation do
+    %Operation{
+      tags: ["Timelines"],
+      summary: "Bookmarked statuses",
+      description: "Statuses the user has bookmarked",
+      operationId: "StatusController.bookmarks",
+      parameters: pagination_params(),
+      security: [%{"oAuth" => ["read:bookmarks"]}],
+      responses: %{
+        200 => Operation.response("Array of Statuses", "application/json", array_of_statuses())
+      }
+    }
+  end
+
+  def show_history_operation do
+    %Operation{
+      tags: ["Retrieve status history"],
+      summary: "Status history",
+      description: "View history of a status",
+      operationId: "StatusController.show_history",
+      security: [%{"oAuth" => ["read:statuses"]}],
+      parameters: [
+        id_param()
+      ],
+      responses: %{
+        200 => status_history_response(),
+        404 => Operation.response("Not Found", "application/json", ApiError)
+      }
+    }
+  end
+
+  def show_source_operation do
+    %Operation{
+      tags: ["Retrieve status source"],
+      summary: "Status source",
+      description: "View source of a status",
+      operationId: "StatusController.show_source",
+      security: [%{"oAuth" => ["read:statuses"]}],
+      parameters: [
+        id_param()
+      ],
+      responses: %{
+        200 => status_source_response(),
+        404 => Operation.response("Not Found", "application/json", ApiError)
+      }
+    }
+  end
+
+  def update_operation do
+    %Operation{
+      tags: ["Update status"],
+      summary: "Update status",
+      description: "Change the content of a status",
+      operationId: "StatusController.update",
+      security: [%{"oAuth" => ["write:statuses"]}],
+      parameters: [
+        id_param()
+      ],
+      requestBody: request_body("Parameters", update_request(), required: true),
+      responses: %{
+        200 => status_response(),
+        403 => Operation.response("Forbidden", "application/json", ApiError),
+        404 => Operation.response("Not Found", "application/json", ApiError)
+      }
+    }
+  end
+
+  def array_of_statuses do
+    %Schema{type: :array, items: Status, example: [Status.schema().example]}
+  end
+
+  defp create_request do
+    %Schema{
+      title: "StatusCreateRequest",
+      type: :object,
+      properties: %{
+        status: %Schema{
+          type: :string,
+          nullable: true,
+          description:
+            "Text content of the status. If `media_ids` is provided, this becomes optional. Attaching a `poll` is optional while `status` is provided."
+        },
+        media_ids: %Schema{
+          nullable: true,
+          type: :array,
+          items: %Schema{type: :string},
+          description: "Array of Attachment ids to be attached as media."
+        },
+        poll: poll_params(),
+        in_reply_to_id: %Schema{
+          nullable: true,
+          allOf: [FlakeID],
+          description: "ID of the status being replied to, if status is a reply"
+        },
+        sensitive: %Schema{
+          allOf: [BooleanLike],
+          nullable: true,
+          description: "Mark status and attached media as sensitive?"
+        },
+        spoiler_text: %Schema{
+          type: :string,
+          nullable: true,
+          description:
+            "Text to be shown as a warning or subject before the actual content. Statuses are generally collapsed behind this field."
+        },
+        scheduled_at: %Schema{
+          type: :string,
+          format: :"date-time",
+          nullable: true,
+          description:
+            "ISO 8601 Datetime at which to schedule a status. Providing this paramter will cause ScheduledStatus to be returned instead of Status. Must be at least 5 minutes in the future."
+        },
+        language: %Schema{
+          type: :string,
+          nullable: true,
+          description: "ISO 639 language code for this status."
+        },
+        # Pleroma-specific properties:
+        preview: %Schema{
+          allOf: [BooleanLike],
+          nullable: true,
+          description:
+            "If set to `true` the post won't be actually posted, but the status entitiy would still be rendered back. This could be useful for previewing rich text/custom emoji, for example"
+        },
+        content_type: %Schema{
+          type: :string,
+          nullable: true,
+          description:
+            "The MIME type of the status, it is transformed into HTML by the backend. You can get the list of the supported MIME types with the nodeinfo endpoint."
+        },
+        to: %Schema{
+          type: :array,
+          nullable: true,
+          items: %Schema{type: :string},
+          description:
+            "A list of nicknames (like `lain@soykaf.club` or `lain` on the local server) that will be used to determine who is going to be addressed by this post. Using this will disable the implicit addressing by mentioned names in the `status` body, only the people in the `to` list will be addressed. The normal rules for for post visibility are not affected by this and will still apply"
+        },
+        visibility: %Schema{
+          nullable: true,
+          anyOf: [
+            VisibilityScope,
+            %Schema{type: :string, description: "`list:LIST_ID`", example: "LIST:123"}
+          ],
+          description:
+            "Visibility of the posted status. Besides standard MastoAPI values (`direct`, `private`, `unlisted` or `public`) it can be used to address a List by setting it to `list:LIST_ID`"
+        },
+        expires_in: %Schema{
+          nullable: true,
+          type: :integer,
+          description:
+            "The number of seconds the posted activity should expire in. When a posted activity expires it will be deleted from the server, and a delete request for it will be federated. This needs to be longer than an hour."
+        },
+        in_reply_to_conversation_id: %Schema{
+          nullable: true,
+          type: :string,
+          description:
+            "Will reply to a given conversation, addressing only the people who are part of the recipient set of that conversation. Sets the visibility to `direct`."
+        }
+      },
+      example: %{
+        "status" => "What time is it?",
+        "sensitive" => "false",
+        "poll" => %{
+          "options" => ["Cofe", "Adventure"],
+          "expires_in" => 420
+        }
+      }
+    }
+  end
+
+  defp update_request do
+    %Schema{
+      title: "StatusUpdateRequest",
+      type: :object,
+      properties: %{
+        status: %Schema{
+          type: :string,
+          nullable: true,
+          description:
+            "Text content of the status. If `media_ids` is provided, this becomes optional. Attaching a `poll` is optional while `status` is provided."
+        },
+        media_ids: %Schema{
+          nullable: true,
+          type: :array,
+          items: %Schema{type: :string},
+          description: "Array of Attachment ids to be attached as media."
+        },
+        poll: poll_params(),
+        sensitive: %Schema{
+          allOf: [BooleanLike],
+          nullable: true,
+          description: "Mark status and attached media as sensitive?"
+        },
+        spoiler_text: %Schema{
+          type: :string,
+          nullable: true,
+          description:
+            "Text to be shown as a warning or subject before the actual content. Statuses are generally collapsed behind this field."
+        },
+        content_type: %Schema{
+          type: :string,
+          nullable: true,
+          description:
+            "The MIME type of the status, it is transformed into HTML by the backend. You can get the list of the supported MIME types with the nodeinfo endpoint."
+        },
+        to: %Schema{
+          type: :array,
+          nullable: true,
+          items: %Schema{type: :string},
+          description:
+            "A list of nicknames (like `lain@soykaf.club` or `lain` on the local server) that will be used to determine who is going to be addressed by this post. Using this will disable the implicit addressing by mentioned names in the `status` body, only the people in the `to` list will be addressed. The normal rules for for post visibility are not affected by this and will still apply"
+        }
+      },
+      example: %{
+        "status" => "What time is it?",
+        "sensitive" => "false",
+        "poll" => %{
+          "options" => ["Cofe", "Adventure"],
+          "expires_in" => 420
+        }
+      }
+    }
+  end
+
+  def poll_params do
+    %Schema{
+      nullable: true,
+      type: :object,
+      required: [:options, :expires_in],
+      properties: %{
+        options: %Schema{
+          type: :array,
+          items: %Schema{type: :string},
+          description: "Array of possible answers. Must be provided with `poll[expires_in]`."
+        },
+        expires_in: %Schema{
+          type: :integer,
+          nullable: true,
+          description:
+            "Duration the poll should be open, in seconds. Must be provided with `poll[options]`"
+        },
+        multiple: %Schema{
+          allOf: [BooleanLike],
+          nullable: true,
+          description: "Allow multiple choices?"
+        },
+        hide_totals: %Schema{
+          allOf: [BooleanLike],
+          nullable: true,
+          description: "Hide vote counts until the poll ends?"
+        }
+      }
+    }
+  end
+
+  def id_param do
+    Operation.parameter(:id, :path, FlakeID, "Status ID",
+      example: "9umDrYheeY451cQnEe",
+      required: true
+    )
+  end
+
+  defp status_response do
+    Operation.response("Status", "application/json", Status)
+  end
+
+  defp status_history_response do
+    Operation.response(
+      "Status History",
+      "application/json",
+      %Schema{
+        title: "Status history",
+        description: "Response schema for history of a status",
+        type: :array,
+        items: %Schema{
+          type: :object,
+          properties: %{
+            account: %Schema{
+              allOf: [Account],
+              description: "The account that authored this status"
+            },
+            content: %Schema{
+              type: :string,
+              format: :html,
+              description: "HTML-encoded status content"
+            },
+            sensitive: %Schema{
+              type: :boolean,
+              description: "Is this status marked as sensitive content?"
+            },
+            spoiler_text: %Schema{
+              type: :string,
+              description:
+                "Subject or summary line, below which status content is collapsed until expanded"
+            },
+            created_at: %Schema{
+              type: :string,
+              format: "date-time",
+              description: "The date when this status was created"
+            },
+            media_attachments: %Schema{
+              type: :array,
+              items: Attachment,
+              description: "Media that is attached to this status"
+            },
+            emojis: %Schema{
+              type: :array,
+              items: Emoji,
+              description: "Custom emoji to be used when rendering status content"
+            },
+            poll: %Schema{
+              allOf: [Poll],
+              nullable: true,
+              description: "The poll attached to the status"
+            }
+          }
+        }
+      }
+    )
+  end
+
+  defp status_source_response do
+    Operation.response(
+      "Status Source",
+      "application/json",
+      %Schema{
+        type: :object,
+        properties: %{
+          id: FlakeID,
+          text: %Schema{
+            type: :string,
+            description: "Raw source of status content"
+          },
+          spoiler_text: %Schema{
+            type: :string,
+            description:
+              "Subject or summary line, below which status content is collapsed until expanded"
+          },
+          content_type: %Schema{
+            type: :string,
+            description: "The content type of the source"
+          }
+        }
+      }
+    )
+  end
+
+  defp context do
+    %Schema{
+      title: "StatusContext",
+      description:
+        "Represents the tree around a given status. Used for reconstructing threads of statuses.",
+      type: :object,
+      required: [:ancestors, :descendants],
+      properties: %{
+        ancestors: array_of_statuses(),
+        descendants: array_of_statuses()
+      },
+      example: %{
+        "ancestors" => [Status.schema().example],
+        "descendants" => [Status.schema().example]
+      }
+    }
+  end
+end