Add ScheduledStatuses methods (#409)

* Ensure ScheduledStatus entity is up-to-date

* Implement ScheduledStatuses methods

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

@@ -0,0 +1,72 @@
+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.ScheduledStatus
+import social.bigbone.api.method.ScheduledStatusMethods
+import java.time.Instant
+
+/**
+ * Reactive implementation of [ScheduledStatusMethods].
+ *
+ * Manage statuses that were scheduled to be published at a future date.
+ *
+ * @see <a href="https://docs.joinmastodon.org/methods/scheduled_statuses/">Mastodon scheduled_statuses API methods</a>
+ */
+class RxScheduledStatusMethods(client: MastodonClient) {
+
+    private val scheduledStatusMethods = ScheduledStatusMethods(client)
+
+    /**
+     * View scheduled statuses.
+     *
+     * @param range optional Range for the pageable return value.
+     *
+     * @see <a href="https://docs.joinmastodon.org/methods/scheduled_statuses/#get">Mastodon API documentation: methods/scheduled_statuses/#get</a>
+     */
+    @JvmOverloads
+    fun getScheduledStatuses(range: Range = Range()): Single<Pageable<ScheduledStatus>> = Single.fromCallable {
+        scheduledStatusMethods.getScheduledStatuses(range).execute()
+    }
+
+    /**
+     * View a single scheduled status.
+     *
+     * @param withId The ID of the [ScheduledStatus] in the database.
+     *
+     * @see <a href="https://docs.joinmastodon.org/methods/scheduled_statuses/#get-one">Mastodon API documentation: methods/scheduled_statuses/#get-one</a>
+     */
+    fun getScheduledStatus(withId: String): Single<ScheduledStatus> = Single.fromCallable {
+        scheduledStatusMethods.getScheduledStatus(withId).execute()
+    }
+
+    /**
+     * Update a scheduled status’ publishing date.
+     *
+     * @param ofId The ID of the [ScheduledStatus] in the database.
+     * @param newPublishingDate Datetime at which the status will be published. Must lie at least 5 minutes ahead.
+     *
+     * @see <a href="https://docs.joinmastodon.org/methods/scheduled_statuses/#update">Mastodon API documentation: methods/scheduled_statuses/#update</a>
+     * @throws IllegalArgumentException if [newPublishingDate] is not at least 5 minutes ahead.
+     */
+    fun updatePublishingDate(
+        ofId: String,
+        newPublishingDate: Instant
+    ): Single<ScheduledStatus> = Single.fromCallable {
+        scheduledStatusMethods.updatePublishingDate(ofId, newPublishingDate).execute()
+    }
+
+    /**
+     * Cancel a scheduled status.
+     *
+     * @param withId The ID of the [ScheduledStatus] in the database.
+     *
+     * @see <a href="https://docs.joinmastodon.org/methods/scheduled_statuses/#cancel">Mastodon API documentation: methods/scheduled_statuses/#cancel</a>
+     */
+    fun cancelScheduledStatus(withId: String): Completable = Completable.fromAction {
+        scheduledStatusMethods.cancelScheduledStatus(withId)
+    }
+}

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

@@ -58,6 +58,7 @@ import social.bigbone.api.method.PollMethods
 import social.bigbone.api.method.PreferenceMethods
 import social.bigbone.api.method.PushNotificationMethods
 import social.bigbone.api.method.ReportMethods
+import social.bigbone.api.method.ScheduledStatusMethods
 import social.bigbone.api.method.SearchMethods
 import social.bigbone.api.method.StatusMethods
 import social.bigbone.api.method.StreamingMethods
@@ -370,6 +371,13 @@ private constructor(
     @get:JvmName("reports")
     val reports: ReportMethods by lazy { ReportMethods(this) }
 
+    /**
+     * Access API methods under the "scheduled_statuses" endpoint.
+     */
+    @Suppress("unused") // public API
+    @get:JvmName("scheduledStatuses")
+    val scheduledStatuses: ScheduledStatusMethods by lazy { ScheduledStatusMethods(this) }
+
     /**
      * Access API methods under the "search" endpoint.
      */

bigbone/src/main/kotlin/social/bigbone/api/entity/ScheduledStatus.kt

@@ -16,6 +16,7 @@ import social.bigbone.api.entity.data.Visibility
 data class ScheduledStatus(
     /**
      * ID of the scheduled status in the database.
+     * String cast from an Integer, but not guaranteed to be a number.
      */
     @SerialName("id")
     val id: String = "",
@@ -73,13 +74,13 @@ data class ScheduledStatus(
          * The text of the content warning or summary for the status.
          */
         @SerialName("spoiler_text")
-        val spoilerText: String = "",
+        val spoilerText: String? = null,
 
         /**
          * The visibility that the status will have once it is posted.
          */
         @SerialName("visibility")
-        val visibility: Visibility = Visibility.PUBLIC,
+        val visibility: Visibility? = null,
 
         /**
          * ID of the Status that will be replied to.
@@ -88,7 +89,8 @@ data class ScheduledStatus(
         val inReplyToId: String? = null,
 
         /**
-         * The language that will be used for the status (ISO 639-1 two-letter language code).
+         * The language that will be used for the status.
+         * String representing the ISO 639-1 two-letter language code.
          */
         @SerialName("language")
         val language: String? = null,

bigbone/src/main/kotlin/social/bigbone/api/method/ScheduledStatusMethods.kt

@@ -0,0 +1,97 @@
+package social.bigbone.api.method
+
+import social.bigbone.MastodonClient
+import social.bigbone.MastodonClient.Method
+import social.bigbone.MastodonRequest
+import social.bigbone.Parameters
+import social.bigbone.api.Pageable
+import social.bigbone.api.Range
+import social.bigbone.api.entity.ScheduledStatus
+import java.time.Duration
+import java.time.Instant
+
+/**
+ * Minimum [Duration] a scheduled status needs to be scheduled into the future.
+ */
+private val SCHEDULED_AT_MIN_AHEAD: Duration = Duration.ofMinutes(5)
+
+/**
+ * Manage statuses that were scheduled to be published at a future date.
+ *
+ * @see <a href="https://docs.joinmastodon.org/methods/scheduled_statuses/">Mastodon scheduled_statuses API methods</a>
+ */
+class ScheduledStatusMethods(private val client: MastodonClient) {
+
+    private val endpoint = "api/v1/scheduled_statuses"
+
+    /**
+     * View scheduled statuses.
+     *
+     * @param range optional Range for the pageable return value.
+     *
+     * @see <a href="https://docs.joinmastodon.org/methods/scheduled_statuses/#get">Mastodon API documentation: methods/scheduled_statuses/#get</a>
+     */
+    @JvmOverloads
+    fun getScheduledStatuses(range: Range = Range()): MastodonRequest<Pageable<ScheduledStatus>> {
+        return client.getPageableMastodonRequest<ScheduledStatus>(
+            endpoint = endpoint,
+            method = Method.GET,
+            parameters = range.toParameters()
+        )
+    }
+
+    /**
+     * View a single scheduled status.
+     *
+     * @param withId The ID of the [ScheduledStatus] in the database.
+     *
+     * @see <a href="https://docs.joinmastodon.org/methods/scheduled_statuses/#get-one">Mastodon API documentation: methods/scheduled_statuses/#get-one</a>
+     */
+    fun getScheduledStatus(withId: String): MastodonRequest<ScheduledStatus> {
+        return client.getMastodonRequest(
+            endpoint = "$endpoint/$withId",
+            method = Method.GET
+        )
+    }
+
+    /**
+     * Update a scheduled status’ publishing date.
+     *
+     * @param ofId The ID of the [ScheduledStatus] in the database.
+     * @param newPublishingDate Datetime at which the status will be published.
+     * Must lie at least [SCHEDULED_AT_MIN_AHEAD] minutes ahead.
+     *
+     * @see <a href="https://docs.joinmastodon.org/methods/scheduled_statuses/#update">Mastodon API documentation: methods/scheduled_statuses/#update</a>
+     * @throws IllegalArgumentException if [newPublishingDate] is not at least [SCHEDULED_AT_MIN_AHEAD] minutes ahead.
+     */
+    fun updatePublishingDate(
+        ofId: String,
+        newPublishingDate: Instant
+    ): MastodonRequest<ScheduledStatus> {
+        require(newPublishingDate.isAfter(Instant.now().plus(SCHEDULED_AT_MIN_AHEAD))) {
+            "New publishing date must lie ahead at least ${SCHEDULED_AT_MIN_AHEAD.toMinutes()} minutes"
+        }
+
+        return client.getMastodonRequest(
+            endpoint = "$endpoint/$ofId",
+            method = Method.PUT,
+            parameters = Parameters().apply {
+                append("scheduled_at", newPublishingDate.toString())
+            }
+        )
+    }
+
+    /**
+     * Cancel a scheduled status.
+     *
+     * @param withId The ID of the [ScheduledStatus] in the database.
+     *
+     * @see <a href="https://docs.joinmastodon.org/methods/scheduled_statuses/#cancel">Mastodon API documentation: methods/scheduled_statuses/#cancel</a>
+     */
+    fun cancelScheduledStatus(withId: String) {
+        return client.performAction(
+            endpoint = "$endpoint/$withId",
+            method = Method.DELETE
+        )
+    }
+}

bigbone/src/test/assets/scheduled_statuses_get_status_success.json

@@ -0,0 +1,17 @@
+{
+  "id": "3221",
+  "scheduled_at": "2019-12-05T12:33:01.000Z",
+  "params": {
+    "poll": null,
+    "text": "test content",
+    "media_ids": null,
+    "sensitive": null,
+    "visibility": null,
+    "idempotency": null,
+    "scheduled_at": null,
+    "spoiler_text": null,
+    "application_id": 596551,
+    "in_reply_to_id": null
+  },
+  "media_attachments": []
+}

bigbone/src/test/assets/scheduled_statuses_get_statuses_success.json

@@ -0,0 +1,19 @@
+[
+  {
+    "id": "3221",
+    "scheduled_at": "2019-12-05T12:33:01.000Z",
+    "params": {
+      "poll": null,
+      "text": "test content",
+      "media_ids": null,
+      "sensitive": null,
+      "visibility": null,
+      "idempotency": null,
+      "scheduled_at": null,
+      "spoiler_text": null,
+      "application_id": 596551,
+      "in_reply_to_id": null
+    },
+    "media_attachments": []
+  }
+]

bigbone/src/test/assets/scheduled_statuses_update_success.json

@@ -0,0 +1,17 @@
+{
+  "id": "3221",
+  "scheduled_at": "2019-12-05T13:33:01.000Z",
+  "params": {
+    "poll": null,
+    "text": "test content",
+    "media_ids": null,
+    "sensitive": null,
+    "visibility": null,
+    "idempotency": null,
+    "scheduled_at": null,
+    "spoiler_text": null,
+    "application_id": 596551,
+    "in_reply_to_id": null
+  },
+  "media_attachments": []
+}