Add Admin::CanonicalEmailBlocks methods (#403)

* Add Admin::CanonicalEmailBlock entity

* Add Admin::CanonicalEmailBlock methods

* Add unit tests

* Update documentation

bigbone-rx/src/main/kotlin/social/bigbone/rx/admin/RxAdminCanonicalEmailBlockMethods.kt

@@ -0,0 +1,81 @@
+package social.bigbone.rx.admin
+
+import io.reactivex.rxjava3.core.Completable
+import io.reactivex.rxjava3.core.Single
+import social.bigbone.MastodonClient
+import social.bigbone.api.Pageable
+import social.bigbone.api.Range
+import social.bigbone.api.entity.admin.AdminCanonicalEmailBlock
+import social.bigbone.api.entity.admin.BlockCanonicalEmailVariant
+import social.bigbone.api.method.admin.AdminCanonicalEmailBlockMethods
+
+/**
+ * Reactive implementation of [AdminCanonicalEmailBlockMethods].
+ *
+ * Block certain email addresses by their hash.
+ *
+ * @see <a href="https://docs.joinmastodon.org/methods/admin/canonical_email_blocks/">Mastodon admin/canonical_email_blocks API methods</a>
+ */
+class RxAdminCanonicalEmailBlockMethods(client: MastodonClient) {
+
+    private val adminCanonicalEmailBlockMethods = AdminCanonicalEmailBlockMethods(client)
+
+    /**
+     * List all canonical email blocks.
+     *
+     * @param range optional Range for the pageable return value
+     *
+     * @see <a href="https://docs.joinmastodon.org/methods/admin/canonical_email_blocks/#get">
+     *     Mastodon API documentation: admin/canonical_email_blocks/#get</a>
+     */
+    @JvmOverloads
+    fun getAllCanonicalEmailBlocks(range: Range = Range()): Single<Pageable<AdminCanonicalEmailBlock>> =
+        Single.fromCallable { adminCanonicalEmailBlockMethods.getAllCanonicalEmailBlocks(range).execute() }
+
+    /**
+     * Show a single canonical email block.
+     *
+     * @param id The ID of the Admin::CanonicalEmailBlock in the database.
+     *
+     * @see <a href="https://docs.joinmastodon.org/methods/admin/canonical_email_blocks/#get-one">
+     *     Mastodon API documentation: admin/canonical_email_blocks/#get-one</a>
+     */
+    fun getCanonicalEmailBlock(id: String): Single<AdminCanonicalEmailBlock> = Single.fromCallable {
+        adminCanonicalEmailBlockMethods.getCanonicalEmailBlock(id).execute()
+    }
+
+    /**
+     * Block a canonical email.
+     *
+     * @param variant One of [BlockCanonicalEmailVariant]s to define how to block a canonical email.
+     *
+     * @see <a href="https://docs.joinmastodon.org/methods/admin/canonical_email_blocks/#create">
+     *     Mastodon API documentation: admin/canonical_email_blocks/#create</a>
+     */
+    fun blockCanonicalEmail(variant: BlockCanonicalEmailVariant): Single<AdminCanonicalEmailBlock> =
+        Single.fromCallable { adminCanonicalEmailBlockMethods.blockCanonicalEmail(variant).execute() }
+
+    /**
+     * Delete a canonical email block.
+     *
+     * @param id The ID of the Admin::CanonicalEmailBlock in the database.
+     *
+     * @see <a href="https://docs.joinmastodon.org/methods/admin/canonical_email_blocks/#delete">
+     *     Mastodon API documentation: admin/canonical_email_blocks/#delete</a>
+     */
+    fun removeCanonicalEmailBlock(id: String) = Completable.fromAction {
+        adminCanonicalEmailBlockMethods.removeCanonicalEmailBlock(id)
+    }
+
+    /**
+     * Canonicalize and hash an email address.
+     *
+     * @param emailAddress The email to canonicalize and hash.
+     * @return All matching canonical email blocks.
+     *
+     * @see <a href="https://docs.joinmastodon.org/methods/admin/canonical_email_blocks/#test">
+     *     Mastodon API documentation admin/canonical_email_blocks/#test</a>
+     */
+    fun canonicalizeAndHashEmailAddress(emailAddress: String): Single<List<AdminCanonicalEmailBlock>> =
+        Single.fromCallable { adminCanonicalEmailBlockMethods.canonicalizeAndHashEmailAddress(emailAddress).execute() }
+}

bigbone/src/main/kotlin/social/bigbone/MastodonClient.kt

@@ -65,6 +65,7 @@ import social.bigbone.api.method.SuggestionMethods
 import social.bigbone.api.method.TagMethods
 import social.bigbone.api.method.TimelineMethods
 import social.bigbone.api.method.TrendMethods
+import social.bigbone.api.method.admin.AdminCanonicalEmailBlockMethods
 import social.bigbone.api.method.admin.AdminDimensionMethods
 import social.bigbone.api.method.admin.AdminDomainBlockMethods
 import social.bigbone.api.method.admin.AdminEmailDomainBlockMethods
@@ -107,6 +108,13 @@ private constructor(
     @get:JvmName("accounts")
     val accounts: AccountMethods by lazy { AccountMethods(this) }
 
+    /**
+     * Access API methods under the "admin/canonical_email_blocks" endpoint.
+     */
+    @Suppress("unused") // public API
+    @get:JvmName("adminCanonicalEmailBlocks")
+    val adminCanonicalEmailBlocks: AdminCanonicalEmailBlockMethods by lazy { AdminCanonicalEmailBlockMethods(this) }
+
     /**
      * Access API methods under the "admin/dimensions" endpoint.
      */

bigbone/src/main/kotlin/social/bigbone/api/entity/admin/AdminCanonicalEmailBlock.kt

@@ -0,0 +1,63 @@
+package social.bigbone.api.entity.admin
+
+import kotlinx.serialization.SerialName
+import kotlinx.serialization.Serializable
+import social.bigbone.Parameters
+import social.bigbone.api.method.admin.AdminCanonicalEmailBlockMethods
+
+/**
+ * Block certain email addresses by their hash.
+ *
+ * @see <a href="https://docs.joinmastodon.org/entities/Admin_CanonicalEmailBlock/">Mastodon documentation Admin::CanonicalEmailBlock</a>
+ */
+@Serializable
+data class AdminCanonicalEmailBlock(
+    /**
+     * The ID of the email block in the database.
+     * String cast from Integer, but not guaranteed to be a number.
+     */
+    @SerialName("id")
+    val id: String,
+
+    /**
+     * The SHA256 hash of the canonical email address.
+     */
+    @SerialName("canonical_email_hash")
+    val canonicalEmailHash: String
+)
+
+/**
+ * Means of blocking a canonical email address.
+ *
+ * When blocking a canonical email address via [AdminCanonicalEmailBlockMethods.blockCanonicalEmail], the Mastodon API offers 2 variants:
+ *
+ *   1. By email address
+ *   2. By canonical email hash
+ *
+ * If either one is supplied, the other one is ignored. To ensure that this fact is understood, this sealed class
+ * is used to wrap those two options, disallowing consumers to ever use both at the same time.
+ */
+sealed class BlockCanonicalEmailVariant(val apiKey: String, val value: String) {
+    /**
+     * Used to block a canonical email via an email address.
+     *
+     * @property email The email address to block
+     */
+    data class ByEmail(val email: String) : BlockCanonicalEmailVariant(
+        apiKey = "email",
+        value = email
+    )
+
+    /**
+     * Used to block a canonical email via a hash.
+     *
+     * @property canonicalEmailHash The email hash to block
+     */
+    data class ByHash(val canonicalEmailHash: String) : BlockCanonicalEmailVariant(
+        apiKey = "canonical_email_hash",
+        value = canonicalEmailHash
+    )
+
+    internal fun appendToParameters(parameters: Parameters = Parameters()): Parameters =
+        parameters.apply { append(apiKey, value) }
+}

bigbone/src/main/kotlin/social/bigbone/api/method/admin/AdminCanonicalEmailBlockMethods.kt

@@ -0,0 +1,99 @@
+package social.bigbone.api.method.admin
+
+import social.bigbone.MastodonClient
+import social.bigbone.MastodonRequest
+import social.bigbone.Parameters
+import social.bigbone.api.Pageable
+import social.bigbone.api.Range
+import social.bigbone.api.entity.admin.AdminCanonicalEmailBlock
+import social.bigbone.api.entity.admin.BlockCanonicalEmailVariant
+
+/**
+ * Block certain email addresses by their hash.
+ *
+ * @see <a href="https://docs.joinmastodon.org/methods/admin/canonical_email_blocks/">Mastodon admin/canonical_email_blocks API methods</a>
+ */
+class AdminCanonicalEmailBlockMethods(private val client: MastodonClient) {
+
+    private val adminCanonicalEmailBlockEndpoint = "api/v1/admin/canonical_email_blocks"
+
+    /**
+     * List all canonical email blocks.
+     *
+     * @param range optional Range for the pageable return value
+     *
+     * @see <a href="https://docs.joinmastodon.org/methods/admin/canonical_email_blocks/#get">
+     *     Mastodon API documentation: admin/canonical_email_blocks/#get</a>
+     */
+    @JvmOverloads
+    fun getAllCanonicalEmailBlocks(range: Range = Range()): MastodonRequest<Pageable<AdminCanonicalEmailBlock>> {
+        return client.getPageableMastodonRequest(
+            endpoint = adminCanonicalEmailBlockEndpoint,
+            method = MastodonClient.Method.GET,
+            parameters = range.toParameters()
+        )
+    }
+
+    /**
+     * Show a single canonical email block.
+     *
+     * @param id The ID of the Admin::CanonicalEmailBlock in the database.
+     *
+     * @see <a href="https://docs.joinmastodon.org/methods/admin/canonical_email_blocks/#get-one">
+     *     Mastodon API documentation: admin/canonical_email_blocks/#get-one</a>
+     */
+    fun getCanonicalEmailBlock(id: String): MastodonRequest<AdminCanonicalEmailBlock> {
+        return client.getMastodonRequest(
+            endpoint = "$adminCanonicalEmailBlockEndpoint/$id",
+            method = MastodonClient.Method.GET
+        )
+    }
+
+    /**
+     * Block a canonical email.
+     *
+     * @param variant One of [BlockCanonicalEmailVariant]s to define how to block a canonical email.
+     *
+     * @see <a href="https://docs.joinmastodon.org/methods/admin/canonical_email_blocks/#create">
+     *     Mastodon API documentation: admin/canonical_email_blocks/#create</a>
+     */
+    fun blockCanonicalEmail(variant: BlockCanonicalEmailVariant): MastodonRequest<AdminCanonicalEmailBlock> {
+        return client.getMastodonRequest(
+            endpoint = adminCanonicalEmailBlockEndpoint,
+            method = MastodonClient.Method.POST,
+            parameters = variant.appendToParameters()
+        )
+    }
+
+    /**
+     * Delete a canonical email block.
+     *
+     * @param id The ID of the Admin::CanonicalEmailBlock in the database.
+     *
+     * @see <a href="https://docs.joinmastodon.org/methods/admin/canonical_email_blocks/#delete">
+     *     Mastodon API documentation: admin/canonical_email_blocks/#delete</a>
+     */
+    fun removeCanonicalEmailBlock(id: String) {
+        client.performAction(
+            endpoint = "$adminCanonicalEmailBlockEndpoint/$id",
+            method = MastodonClient.Method.DELETE
+        )
+    }
+
+    /**
+     * Canonicalize and hash an email address.
+     *
+     * @param emailAddress The email to canonicalize and hash.
+     * @return All matching canonical email blocks.
+     *
+     * @see <a href="https://docs.joinmastodon.org/methods/admin/canonical_email_blocks/#test">
+     *     Mastodon API documentation admin/canonical_email_blocks/#test</a>
+     */
+    fun canonicalizeAndHashEmailAddress(emailAddress: String): MastodonRequest<List<AdminCanonicalEmailBlock>> {
+        return client.getMastodonRequestForList(
+            endpoint = "$adminCanonicalEmailBlockEndpoint/test",
+            method = MastodonClient.Method.POST,
+            parameters = Parameters().append("email", emailAddress)
+        )
+    }
+}

bigbone/src/test/assets/admin_canonical_email_blocks_all_blocked_success.json

@@ -0,0 +1,6 @@
+[
+  {
+    "id": "1",
+    "canonical_email_hash": "b344e55d11b3fc25d0d53194e0475838bf17e9be67ce3e6469956222d9a34f9c"
+  }
+]

bigbone/src/test/assets/admin_canonical_email_blocks_block_success.json

@@ -0,0 +1,4 @@
+{
+  "id": "1",
+  "canonical_email_hash": "b344e55d11b3fc25d0d53194e0475838bf17e9be67ce3e6469956222d9a34f9c"
+}

bigbone/src/test/assets/admin_canonical_email_blocks_delete_success.json

@@ -0,0 +1 @@
+{}

bigbone/src/test/assets/admin_canonical_email_blocks_single_success.json

@@ -0,0 +1,4 @@
+{
+  "id": "1",
+  "canonical_email_hash": "b344e55d11b3fc25d0d53194e0475838bf17e9be67ce3e6469956222d9a34f9c"
+}

bigbone/src/test/assets/admin_canonical_email_blocks_test_success.json

@@ -0,0 +1,6 @@
+[
+  {
+    "id": "1",
+    "canonical_email_hash": "b344e55d11b3fc25d0d53194e0475838bf17e9be67ce3e6469956222d9a34f9c"
+  }
+]