From c0dc78fd64b54c1b9bd7d5e6dec3d9a5ce7241ee Mon Sep 17 00:00:00 2001 From: Patrick Geselbracht Date: Fri, 1 Dec 2023 13:57:21 +0100 Subject: [PATCH] Implement Trends API (#360) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Update documentation to reflect what the classes do This goes against Mastodon’s documentation, but their documentation seems to be outdated here. --------- Co-authored-by: Gasser André --- .../social/bigbone/rx/RxTrendMethods.kt | 63 +++++++ .../kotlin/social/bigbone/MastodonClient.kt | 8 + .../social/bigbone/api/entity/TrendsLink.kt | 106 ++++++++++++ .../social/bigbone/api/entity/data/History.kt | 7 +- .../social/bigbone/api/method/TrendMethods.kt | 82 +++++++++ .../trends_view_trending_links_success.json | 55 ++++++ ...trends_view_trending_statuses_success.json | 10 ++ .../trends_view_trending_tags_success.json | 35 ++++ .../bigbone/api/method/TrendMethodsTest.kt | 156 ++++++++++++++++++ docs/api-coverage/trends.md | 12 +- 10 files changed, 526 insertions(+), 8 deletions(-) create mode 100644 bigbone-rx/src/main/kotlin/social/bigbone/rx/RxTrendMethods.kt create mode 100644 bigbone/src/main/kotlin/social/bigbone/api/entity/TrendsLink.kt create mode 100644 bigbone/src/main/kotlin/social/bigbone/api/method/TrendMethods.kt create mode 100644 bigbone/src/test/assets/trends_view_trending_links_success.json create mode 100644 bigbone/src/test/assets/trends_view_trending_statuses_success.json create mode 100644 bigbone/src/test/assets/trends_view_trending_tags_success.json create mode 100644 bigbone/src/test/kotlin/social/bigbone/api/method/TrendMethodsTest.kt diff --git a/bigbone-rx/src/main/kotlin/social/bigbone/rx/RxTrendMethods.kt b/bigbone-rx/src/main/kotlin/social/bigbone/rx/RxTrendMethods.kt new file mode 100644 index 000000000..5f7319929 --- /dev/null +++ b/bigbone-rx/src/main/kotlin/social/bigbone/rx/RxTrendMethods.kt @@ -0,0 +1,63 @@ +package social.bigbone.rx + +import io.reactivex.rxjava3.core.Single +import social.bigbone.MastodonClient +import social.bigbone.api.entity.Status +import social.bigbone.api.entity.Tag +import social.bigbone.api.entity.TrendsLink +import social.bigbone.api.method.TrendMethods + +/** + * Reactive implementation of [TrendMethods]. + * + * View trending tags, statuses, or links, i.e. those that are currently being used more frequently than usual. + * @see Mastodon trends API methods + */ +class RxTrendMethods(client: MastodonClient) { + + private val trendMethods = TrendMethods(client) + + /** + * Tags that are being used more frequently within the past week. + * + * @param offset Skip the first n results. + * @param limit Maximum number of results to return. Defaults to 10 tags. Max 20 tags. + * @see Mastodon API documentation: methods/trends/#tags + */ + @JvmOverloads + fun getTrendingTags( + offset: Int? = null, + limit: Int = 10 + ): Single> = Single.fromCallable { + trendMethods.getTrendingTags(offset, limit).execute() + } + + /** + * Statuses that have been interacted with more than others. + * + * @param offset Skip the first n results. + * @param limit Maximum number of results to return. Defaults to 20 statuses. Max 40 statuses. + * @see Mastodon API documentation: methods/trends/#statuses + */ + fun getTrendingStatuses( + offset: Int? = null, + limit: Int = 20 + ): Single> = Single.fromCallable { + trendMethods.getTrendingStatuses(offset, limit).execute() + } + + /** + * Links that have been shared more than others. + * + * @param offset Skip the first n results. + * @param limit Maximum number of results to return. Defaults to 10 links. Max 20 links. + * @see Mastodon API documentation: methods/trends/#links + */ + @JvmOverloads + fun getTrendingLinks( + offset: Int? = null, + limit: Int = 10 + ): Single> = Single.fromCallable { + trendMethods.getTrendingLinks(offset, limit).execute() + } +} diff --git a/bigbone/src/main/kotlin/social/bigbone/MastodonClient.kt b/bigbone/src/main/kotlin/social/bigbone/MastodonClient.kt index c79dc5939..2b103e86c 100644 --- a/bigbone/src/main/kotlin/social/bigbone/MastodonClient.kt +++ b/bigbone/src/main/kotlin/social/bigbone/MastodonClient.kt @@ -48,6 +48,7 @@ import social.bigbone.api.method.StreamingMethods 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.AdminDimensionMethods import social.bigbone.api.method.admin.AdminMeasureMethods import social.bigbone.api.method.admin.AdminRetentionMethods @@ -336,6 +337,13 @@ private constructor( @get:JvmName("timelines") val timelines: TimelineMethods by lazy { TimelineMethods(this) } + /** + * Access API methods under the "trends" endpoint. + */ + @Suppress("unused") // public API + @get:JvmName("trends") + val trends: TrendMethods by lazy { TrendMethods(this) } + /** * Specifies the HTTP methods / HTTP verb that can be used by this class. */ diff --git a/bigbone/src/main/kotlin/social/bigbone/api/entity/TrendsLink.kt b/bigbone/src/main/kotlin/social/bigbone/api/entity/TrendsLink.kt new file mode 100644 index 000000000..c12f44b84 --- /dev/null +++ b/bigbone/src/main/kotlin/social/bigbone/api/entity/TrendsLink.kt @@ -0,0 +1,106 @@ +package social.bigbone.api.entity + +import kotlinx.serialization.SerialName +import kotlinx.serialization.Serializable +import social.bigbone.api.entity.PreviewCard.CardType +import social.bigbone.api.entity.data.History + +/** + * Represents a rich preview card that is generated using OpenGraph tags from a URL. + * @see Mastodon API PreviewCard/Trends::Link + */ +@Serializable +data class TrendsLink( + /** + * Location of linked resource. + */ + @SerialName("url") + val url: String? = null, + + /** + * Title of linked resource. + */ + @SerialName("title") + val title: String? = null, + + /** + * Description of preview. + */ + @SerialName("description") + val description: String? = null, + + /** + * The type of the preview card. + * @see CardType + */ + @SerialName("type") + val type: CardType = CardType.LINK, + + /** + * The author of the original resource. + */ + @SerialName("author_name") + val authorName: String? = null, + + /** + * A link to the author of the original resource. + */ + @SerialName("author_url") + val authorUrl: String? = null, + + /** + * The provider of the original resource. + */ + @SerialName("provider_name") + val providerName: String? = null, + + /** + * A link to the provider of the original resource. + */ + @SerialName("provider_url") + val providerUrl: String? = null, + + /** + * HTML to be used for generating the preview card. + */ + @SerialName("html") + val html: String? = null, + + /** + * Width of preview, in pixels. + */ + @SerialName("width") + val width: Int? = null, + + /** + * Height of preview, in pixels. + */ + @SerialName("height") + val height: Int? = null, + + /** + * Preview thumbnail. + */ + @SerialName("image") + val image: String? = null, + + /** + * Used for photo embeds, instead of custom html. + */ + @SerialName("embed_url") + val embedUrl: String? = null, + + /** + * A hash computed by the BlurHash algorithm, + * for generating colorful preview thumbnails + * when media has not been downloaded yet. + */ + @SerialName("blurhash") + val blurhash: String? = null, + + /** + * Usage statistics for given days (typically the past week). + */ + @SerialName("history") + val history: List? = null +) diff --git a/bigbone/src/main/kotlin/social/bigbone/api/entity/data/History.kt b/bigbone/src/main/kotlin/social/bigbone/api/entity/data/History.kt index f5c02a7ee..e25db1e28 100644 --- a/bigbone/src/main/kotlin/social/bigbone/api/entity/data/History.kt +++ b/bigbone/src/main/kotlin/social/bigbone/api/entity/data/History.kt @@ -6,6 +6,7 @@ import kotlinx.serialization.Serializable /** * Usage statistics for given days (typically the past week). * @see Mastodon API Tag history + * @see Mastodon API PreviewCard history */ @Serializable data class History( @@ -17,13 +18,15 @@ data class History( val day: String = "", /** - * The counted usage of the tag within that day, string cast from integer. + * The counted statuses or usages of the tag within that day. + * String cast from integer. */ @SerialName("uses") val uses: String = "", /** - * The total of accounts using the tag within that day, string cast from integer. + * The total of accounts using the tag or link within that day. + * String cast from integer. */ @SerialName("accounts") val accounts: String = "" diff --git a/bigbone/src/main/kotlin/social/bigbone/api/method/TrendMethods.kt b/bigbone/src/main/kotlin/social/bigbone/api/method/TrendMethods.kt new file mode 100644 index 000000000..a18e394b6 --- /dev/null +++ b/bigbone/src/main/kotlin/social/bigbone/api/method/TrendMethods.kt @@ -0,0 +1,82 @@ +package social.bigbone.api.method + +import social.bigbone.MastodonClient +import social.bigbone.MastodonRequest +import social.bigbone.Parameters +import social.bigbone.api.entity.Status +import social.bigbone.api.entity.Tag +import social.bigbone.api.entity.TrendsLink + +/** + * View trending tags, statuses, or links, i.e. those that are currently being used more frequently than usual. + * @see Mastodon trends API methods + */ +class TrendMethods(private val client: MastodonClient) { + + private val trendsEndpoint = "api/v1/trends" + + /** + * Tags that are being used more frequently within the past week. + * + * @param offset Skip the first n results. + * @param limit Maximum number of results to return. Defaults to 10 tags. Max 20 tags. + * @see Mastodon API documentation: methods/trends/#tags + */ + @JvmOverloads + fun getTrendingTags( + offset: Int? = null, + limit: Int = 10 + ): MastodonRequest> { + return client.getMastodonRequestForList( + endpoint = "$trendsEndpoint/tags", + method = MastodonClient.Method.GET, + parameters = Parameters().apply { + append("limit", limit) + offset?.let { append("offset", offset) } + } + ) + } + + /** + * Statuses that have been interacted with more than others. + * + * @param offset Skip the first n results. + * @param limit Maximum number of results to return. Defaults to 20 statuses. Max 40 statuses. + * @see Mastodon API documentation: methods/trends/#statuses + */ + fun getTrendingStatuses( + offset: Int? = null, + limit: Int = 20 + ): MastodonRequest> { + return client.getMastodonRequestForList( + endpoint = "$trendsEndpoint/statuses", + method = MastodonClient.Method.GET, + parameters = Parameters().apply { + append("limit", limit) + offset?.let { append("offset", offset) } + } + ) + } + + /** + * Links that have been shared more than others. + * + * @param offset Skip the first n results. + * @param limit Maximum number of results to return. Defaults to 10 links. Max 20 links. + * @see Mastodon API documentation: methods/trends/#links + */ + @JvmOverloads + fun getTrendingLinks( + offset: Int? = null, + limit: Int = 10 + ): MastodonRequest> { + return client.getMastodonRequestForList( + endpoint = "$trendsEndpoint/links", + method = MastodonClient.Method.GET, + parameters = Parameters().apply { + append("limit", limit) + offset?.let { append("offset", offset) } + } + ) + } +} diff --git a/bigbone/src/test/assets/trends_view_trending_links_success.json b/bigbone/src/test/assets/trends_view_trending_links_success.json new file mode 100644 index 000000000..bdcdb87d8 --- /dev/null +++ b/bigbone/src/test/assets/trends_view_trending_links_success.json @@ -0,0 +1,55 @@ +[ + { + "url": "https://www.nbcnews.com/specials/plan-your-vote-2022-elections/index.html", + "title": "Plan Your Vote: 2022 Elections", + "description": "Everything you need to know about the voting rules where you live, including registration, mail-in voting, changes since 2020, and more.", + "type": "link", + "author_name": "NBC News", + "author_url": "", + "provider_name": "NBC News", + "provider_url": "", + "html": "", + "width": 400, + "height": 225, + "image": "https://files.mastodon.social/cache/preview_cards/images/045/027/478/original/0783d5e91a14fd49.jpeg", + "embed_url": "", + "blurhash": "UcQmF#ay~qofj[WBj[j[~qof9Fayofofayay", + "history": [ + { + "day": "1661817600", + "accounts": "7", + "uses": "7" + }, + { + "day": "1661731200", + "accounts": "23", + "uses": "23" + }, + { + "day": "1661644800", + "accounts": "0", + "uses": "0" + }, + { + "day": "1661558400", + "accounts": "0", + "uses": "0" + }, + { + "day": "1661472000", + "accounts": "0", + "uses": "0" + }, + { + "day": "1661385600", + "accounts": "0", + "uses": "0" + }, + { + "day": "1661299200", + "accounts": "0", + "uses": "0" + } + ] + } +] diff --git a/bigbone/src/test/assets/trends_view_trending_statuses_success.json b/bigbone/src/test/assets/trends_view_trending_statuses_success.json new file mode 100644 index 000000000..d8d7a9809 --- /dev/null +++ b/bigbone/src/test/assets/trends_view_trending_statuses_success.json @@ -0,0 +1,10 @@ +[ + { + "id": "108910940413327534", + "created_at": "2022-08-30T08:44:26.366Z", + "in_reply_to_id": null, + "in_reply_to_account_id": null, + "sensitive": false, + "content": "

In order to prevent such incidents from happening in the future, we are implementing a fixed set of internal guidelines which must be met before any media content can be shared on our social media platforms. The distribution of material which promotes a message of racism or sexism is unacceptable. We can do better and in the future we will do better.

We apologize again for this incident and can assure you that it will not happen again.

Your Tutanota Team

" + } +] diff --git a/bigbone/src/test/assets/trends_view_trending_tags_success.json b/bigbone/src/test/assets/trends_view_trending_tags_success.json new file mode 100644 index 000000000..f381994a5 --- /dev/null +++ b/bigbone/src/test/assets/trends_view_trending_tags_success.json @@ -0,0 +1,35 @@ +[ + { + "name": "hola", + "url": "https://mastodon.social/tags/hola", + "history": [ + { + "day": "1574726400", + "uses": "13", + "accounts": "10" + } + ] + }, + { + "name": "SaveDotOrg", + "url": "https://mastodon.social/tags/SaveDotOrg", + "history": [ + { + "day": "1574726400", + "uses": "9", + "accounts": "9" + } + ] + }, + { + "name": "introduction", + "url": "https://mastodon.social/tags/introduction", + "history": [ + { + "day": "1574726400", + "uses": "15", + "accounts": "14" + } + ] + } +] diff --git a/bigbone/src/test/kotlin/social/bigbone/api/method/TrendMethodsTest.kt b/bigbone/src/test/kotlin/social/bigbone/api/method/TrendMethodsTest.kt new file mode 100644 index 000000000..3ddc0cbc7 --- /dev/null +++ b/bigbone/src/test/kotlin/social/bigbone/api/method/TrendMethodsTest.kt @@ -0,0 +1,156 @@ +@file:Suppress("MaxLineLength") + +package social.bigbone.api.method + +import io.mockk.slot +import io.mockk.verify +import org.amshove.kluent.shouldBeEqualTo +import org.amshove.kluent.shouldBeFalse +import org.amshove.kluent.shouldBeNull +import org.amshove.kluent.shouldBeNullOrEmpty +import org.amshove.kluent.shouldHaveSize +import org.amshove.kluent.shouldNotBeNull +import org.amshove.kluent.shouldNotBeNullOrEmpty +import org.junit.jupiter.api.Test +import social.bigbone.Parameters +import social.bigbone.PrecisionDateTime.ValidPrecisionDateTime.ExactTime +import social.bigbone.api.entity.PreviewCard +import social.bigbone.api.entity.Status +import social.bigbone.api.entity.Tag +import social.bigbone.api.entity.TrendsLink +import social.bigbone.testtool.MockClient +import java.time.Instant + +class TrendMethodsTest { + + @Test + fun `Given a client returning success, when getting trending tags, then request correct endpoint and serialise response correctly`() { + val client = MockClient.mock(jsonName = "trends_view_trending_tags_success.json") + val trendMethods = TrendMethods(client) + + val tags: List = trendMethods.getTrendingTags().execute() + + with(tags) { + shouldHaveSize(3) + + get(0).name shouldBeEqualTo "hola" + get(1).name shouldBeEqualTo "SaveDotOrg" + get(2).name shouldBeEqualTo "introduction" + + get(0).url shouldBeEqualTo "https://mastodon.social/tags/hola" + get(1).url shouldBeEqualTo "https://mastodon.social/tags/SaveDotOrg" + get(2).url shouldBeEqualTo "https://mastodon.social/tags/introduction" + + get(0).history shouldHaveSize 1 + get(0).history[0].day shouldBeEqualTo "1574726400" + get(0).history[0].uses shouldBeEqualTo "13" + get(0).history[0].accounts shouldBeEqualTo "10" + + get(1).history shouldHaveSize 1 + get(1).history[0].day shouldBeEqualTo "1574726400" + get(1).history[0].uses shouldBeEqualTo "9" + get(1).history[0].accounts shouldBeEqualTo "9" + + get(2).history shouldHaveSize 1 + get(2).history[0].day shouldBeEqualTo "1574726400" + get(2).history[0].uses shouldBeEqualTo "15" + get(2).history[0].accounts shouldBeEqualTo "14" + } + + val parametersCapturingSlot = slot() + verify { + client.get( + path = "api/v1/trends/tags", + query = capture(parametersCapturingSlot) + ) + } + with(parametersCapturingSlot.captured) { + toQuery() shouldBeEqualTo "limit=10" + } + } + + @Test + fun `Given a client returning success, when getting trending statuses, then request correct endpoint and serialise response correctly`() { + val client = MockClient.mock(jsonName = "trends_view_trending_statuses_success.json") + val trendMethods = TrendMethods(client) + + val statuses: List = trendMethods.getTrendingStatuses().execute() + + with(statuses) { + shouldHaveSize(1) + + with(get(0)) { + id shouldBeEqualTo "108910940413327534" + createdAt shouldBeEqualTo ExactTime(Instant.parse("2022-08-30T08:44:26.366Z")) + inReplyToId.shouldBeNull() + inReplyToAccountId.shouldBeNull() + isSensitive.shouldBeFalse() + content.shouldNotBeNullOrEmpty() + } + } + + val parametersCapturingSlot = slot() + verify { + client.get( + path = "api/v1/trends/statuses", + query = capture(parametersCapturingSlot) + ) + } + with(parametersCapturingSlot.captured) { + toQuery() shouldBeEqualTo "limit=20" + } + } + + @Test + fun `Given a client returning success, when getting trending links, then request correct endpoint and serialise response correctly`() { + val client = MockClient.mock(jsonName = "trends_view_trending_links_success.json") + val trendMethods = TrendMethods(client) + + val trendsLinks: List = trendMethods.getTrendingLinks().execute() + + with(trendsLinks) { + shouldHaveSize(1) + + with(get(0)) { + url.shouldNotBeNullOrEmpty() + title shouldBeEqualTo "Plan Your Vote: 2022 Elections" + description.shouldNotBeNullOrEmpty() + type shouldBeEqualTo PreviewCard.CardType.LINK + authorName shouldBeEqualTo "NBC News" + authorUrl.shouldBeNullOrEmpty() + providerName shouldBeEqualTo "NBC News" + providerUrl.shouldBeNullOrEmpty() + html.shouldBeNullOrEmpty() + width shouldBeEqualTo 400 + height shouldBeEqualTo 225 + image.shouldNotBeNullOrEmpty() + embedUrl.shouldBeNullOrEmpty() + blurhash shouldBeEqualTo "UcQmF#ay~qofj[WBj[j[~qof9Fayofofayay" + + with(history) { + shouldNotBeNull() + shouldHaveSize(7) + + get(0).day shouldBeEqualTo "1661817600" + get(0).accounts shouldBeEqualTo "7" + get(0).uses shouldBeEqualTo "7" + + get(6).day shouldBeEqualTo "1661299200" + get(6).accounts shouldBeEqualTo "0" + get(6).uses shouldBeEqualTo "0" + } + } + } + + val parametersCapturingSlot = slot() + verify { + client.get( + path = "api/v1/trends/links", + query = capture(parametersCapturingSlot) + ) + } + with(parametersCapturingSlot.captured) { + toQuery() shouldBeEqualTo "limit=10" + } + } +} diff --git a/docs/api-coverage/trends.md b/docs/api-coverage/trends.md index a889200e3..65e631dc3 100644 --- a/docs/api-coverage/trends.md +++ b/docs/api-coverage/trends.md @@ -19,17 +19,17 @@ View hashtags that are currently being used more frequently than usual. GET /api/v1/trends/tags
View trending tags - - Not implemented yet. + + Fully implemented. GET /api/v1/trends/statuses
View trending statuses - - Not implemented yet. + + Fully implemented. GET /api/v1/trends/links
View trending links - - Not implemented yet. + + Fully implemented.