andregasser / bigbone Goto Github PK

Public.getSearch() uses the endpoint /api/v1/search which has been removed since Mastodon 3.0.0. V2 endpoint needs to be used instead.

The following fields are currently missing in the Instance entity class:

• configuration object: all fields
• rules: all fields

The following fields are currently missing in the Account entity class:

• bot
• discoverable
• group
• avatar_static
• header_static
• last_status_at
• noindex
• fields
• moved
• suspended
• limited

OkHttp3 and Gson leak through the client-side API. Check if really necessary and change if needed. Leaking details to the library users makes it difficult to change implementation details without breaking the API.

The following fields are currently missing in the Relationship entity class:

• showing_reblogs
• notifying
• languages
• blocked_by
• muting_notifications
• requested
• domain_blocking
• endorsed
• note

In order to maintain a consistend code style. It should be integrated into the gradle check command (same as detekt).

There's a postUserNameAndPassword() method that gets an access token by posting user credentials to the /oauth/token endpoint directly while using a "grant_type":"password" parameter:

https://github.com/andregasser/mastodon4j/blob/c19e7a3b728faa345ea71fbdb1231b3e627be2d6/mastodon4j/src/main/kotlin/com/sys1yagi/mastodon4j/api/method/Apps.kt#L90-L118

This method is used in example code of this project, from where I got the idea to also use it in my PR #10.

This parameter seems to be not officially supported by the Mastodon API, which only mentions parameter values authorization_code and client_credentials: Mastodon API documentation for /oauth/token

Apparently, sending username/password works via Mastodon's Doorkeeper configuration here, which explicitly warns about enabling the password grant flow, linking to: https://www.rfc-editor.org/rfc/rfc6819#section-4.4.3

I think we need to deal with this one way or another, although I'm not sure how. We should either

• remove functionality that is not part of the documented API completely, because it might fail at any moment, or at least
• document the above both in code and in places like USAGE.md, and urge users to properly use OAuth instead.

The "Get started" guide (now in USAGE.md after move from README.md) is outdated and/or wrong. Just following it from the top, the third line of code

val statuses: List<Status> = timelines.getPublic().execute()

is the first one to fail, because Timelines apparently hasn't had a getPublic() method for five years. Fixing it to use getHome() instead and dealing with it not returning a List<Status> but Pageable<Status>, this still fails with a Mastodon4jRequestException claiming that I'm unauthorized to do so.

Further down the guide, I see a section about getting the Home Timeline that includes an access token - but that, too, implies that the return value is a List, which it isn't.

In the past, I tried following another part of the guide to get that access token, stumbled upon the incomplete OAuth part, but eventually managed to get some token back from my Mastodon server, only for all attempts at writing a test status to fail, although I requested ALL scope.

Without yet having a full grasp on either Mastodon's API or the way it was implemented here, I'm basically poking random things with a stick to see what moves and what doesn't. I'd love to see working example code that:

• actually implements the complete process to authorize and receive a proper access token, without leaving out some steps
• uses that token to get at least one status from a server (for example the most recent status of the home timeline) and works with it (for example printing its content)
• uses that token to send a status (for example an unlisted "Hello World" status),
• all while having some actually useful comments for the parts left out for some reason.
• EDIT: three items of the comment below should also be handled before closing this.

As the plan is to release this library independently, we should at least do these things to avoid confusion:

• Rename the library
• Change the package structure

The Mastodon API documentation defines examples for many of their entities, e.g. the example for Status entity. We might want to use these examples in our tests, to make sure we're testing against up-to-date examples.

Functions that return timelines are currently spread across various files:

• Timelines.kt contains functionality for the home timeline
• Public.kt contains functionality for public and hashtag timelines
• MastodonLists.kt contains functionality for list timelines

In the Mastodon documentation, all timelines are listed in one place, so we should probably move all functions into Timelines.kt as well.

MastodonClient currently has both a post() and a postUrl() method. After #35 is resolved, the latter can be removed and calls to it be replaced with calls to the former, potentially avoiding cases where postUrl() is used to post to a URL with a different host than what the client is configured for.

Public.getPublic() and Public.getTag() have a local parameter that is used by getLocal... and getFederated... functions in the same file.

The local parameter is only appended if true - if false, nothing happens. I believe that a remote parameter should be appended in these cases. Compare https://docs.joinmastodon.org/methods/timelines/#public

URLs are currently built by simple string concatenation. Building them instead via okhttp3.HttpUrl will make the code involved more readable, and might also prevent some bugs down the line.

Follows.postRemoteFollow() currently posts to /api/v1/follows and returns an Account. Does this actually do anything?

Closest I could find in Mastodon API is the endpoint /api/v1/accounts/:id/follow returning a Relationship. Is that what we actually want to do here, or am I missing something obvious?

https://docs.joinmastodon.org/methods/accounts/#follow

The following fields are currently missing in the Application entity class:

• vapid_key
• client_id
• client_secret

In order to transparently list changed to the library releases. Would be nice if we had a proper changelog with the 2.0.0 release to hightlight, what has changes since we forked mastodon4j.

The current plan is to publish this library on Maven Central. We need to change the gradle build accordingly and set proper configuration (like group id, artifact id, ...)

Just to make sure, everything is allright when we release our 2.0.0 version.
https://central.sonatype.org/publish/requirements/

Detekt provides a separate formatting module which acts as a wrapper over klint. By enabling it, we can enforce a common code formatting style for Kotlin code.

Detekt: https://github.com/detekt/detekt
Klint; https://pinterest.github.io/ktlint/

For code quality reasons, works complementarily to Checkstyle. Should also be added to the gradle check command.

As discussed here, the code in USAGE.md should be merged into our samples collection, currently available in the sample and the sample-kotlinmodules.

Main tasks include:

• Check if samples present in USAGE.md are entirely missing in our samples collection. If yes, add a sample to the samples collection for Java and Kotlin each.
• Delete USAGE.md

The following fields are currently missing in the Status entity class:

• poll
• card
• text
• edited_at
• muted
• bookmarked
• filtered

By looking at the code, I can see a lot of code duplication. Would be cool, if we could clean that up somehow.

README.md is currently a lengthy list containing everything, making it a bit unreadable at times. I suggest to move the following parts into their own files:

• Usage section (into USAGE.md?) so that an implementation reference exists that can be updated separately. A later change could move this into a docs/ directory and expand individual elements as necessary
• Implementation Progress section (into API.md?), also sorting by endpoint hierarchy and checking with Mastodon's documentation which methods might have been added in the meantime.

This would leave the following parts in README.md, where they could be expanded upon:

• Introduction, including link to Mastodon API and "Get Started"
• Semantic Versioning reference
• Contribution
• License

If that is OK, I could work on it and send a PR.

Mastodon provides a Reports API which has API calls that return a Report entity. While we already provide a basic implementation of this endpoint, the Report entity currently does not implement all the fields returned by Mastodon servers. The following fields are missing and should be added to the entity:

• action_taken_at
• category
• comment
• forwarded
• created_at
• status_ids
• rule_ids
• target_account

The Report entity is documented here:
https://docs.joinmastodon.org/entities/Report/

Please consult the following documents to make sure your contribution meets our projects criteria:

• Code of Conduct
• Code Contribution Guidelines

The following fields are currently missing in the Attachment entity class:

• meta
• description
• blurhash

Let's try to create an integration test with testcontainers and a docker-compose setup. I already have the docker-compose part ready. Just need to get started with the testcontainers part.

Originally posted to #5:

Currently, basically every API method looks like this:

    fun getAccount(accountId: Long): MastodonRequest<Account> {
        return MastodonRequest(
            { client.get("api/v1/accounts/$accountId") },
            { client.getSerializer().fromJson(it, Account::class.java) }
        )
    }

with the Gson instance being exposed via MastodonClient.getSerializer(). It is probably cleaner to change this into something like a call to client.getMastodonRequest(...), which would deal with the necessary serialization in our MastodonClient instead.

Includes the following tasks:

• Bump version to 2.0.0
• Add CONTRIBUTING.md
• README.md: Update artifact coordinates in README.md
• Publish to Maven Central
• README.md: Update badges

In order to plan releases after 2.0.0, we should have some sort of a release roadmap, which outlines what we are working on next. It does not have to be a huge or so, but just help us to prioritize issues to work on and group them into potential releases. Also, we should make sure, we can group breaking changes together as good as we can.

Our method classes should be aligned with the API documentation structure that is offered in the documentation, as it makes using our API easier. People find methods they're looking for quicker. For example "instance" is listed as a separat "APi method" in the documentation, wheras in our API, methods are hidden in other places, such as "Public.kt". In this case, it would make sense to introduce a separate method class called "Instance".

A similar case is "search" any probably others as well.

Some entities in the "entity" package specify an "id" attribute of type Long. According to the API docs, ids are not guarenteed to be numeric and should have a data type of String instead. Alle entities should quickly be reviewed against API documentation and data type switched if necessary.

Mastodon provides a Notifications API which has API calls that return a Notification entity. While we already provide a basic implementation of this endpoint, the Notification entity currently does not implement all the fields returned by Mastodon servers. The following fields are missing and should be added to the entity:

• report

The Notification entity is documented here:
https://docs.joinmastodon.org/entities/Notification/

Please consult the following documents to make sure your contribution meets our projects criteria:

• Code of Conduct
• Code Contribution Guidelines

he following fields are currently missing in the CustomEmoji entity class:

• category

The site is here: https://docs.joinmastodon.org/client/libraries/#java
We can probably just create a pull request on their repo (did not check in detail yet).
We'll do this after our library 2.0.0 release is either pushed to JitPack or MavenCentral (to be discussed).

In API.md, I have started to document all the endpoint that Mastodon servers offer today. We know that a lot of endpoints are not yet implemented in Bigbone, but there are also endpoints which are only implemented partially (basic functionality might be there, but some special parameters might not be supported, just to give an example).

This list is not yet complete and I need to go through each endpoint and document, if all the query options are supported or not. If not, I need to quickly take a note on what is missing.

After that list is created, we can plan the next feature releases where we add more endpoint functionality.

The current api for media upload is complicated and requires multiple steps, which are not super well documented (already in the original mastodon4j code).
Provide a simple Media.upload() method / builder, that 'asks' for the required parts and does the magic of MultipartBody.Part handling under the covers. One option would be some fromFile() and/or fromResource() / fromUrl() builder methods to upload the actual content.

RxJava should be upgraded to the latest version 3.1.5 as the current version 2.2.21 is end-of-life.
See this for more details: https://github.com/ReactiveX/RxJava

All of the API functionality we offer should be documented using proper Kdoc. This will help users of this library by displaying information about any functionality they might want to use directly in their IDE.

The following fields are currently missing in the MastodonList entity class:

• replies_policy

Most of the API method names have the HTTP request type prefixed, such as postReblog(...) or postUnreblog in Statuses.kt. This could be simplified into just reblog(..) and unreblog(...). Of course there are cases where a prefix like get is completely valid. Those should stay of course.

When changes are pushed into master, I would like to automatically push a new snapshot build to Maven Central. Now it's a manual process. A GItHub action needs to be built for this that performs a gradlew publish command more or less.

In MastodonLists.getLists, we're returning a Pageable without using a range parameter - which every other function returning a Pageable has as one of its parameters, e.g. the function directly below.

I couldn't immediately figure out if this is OK or a bug, so I'm listing it here.

Let's create a new wiki page "API Support" and put contents in there based on the discussion here: #13

In order to maintain consistent code quality.

This project seems to be currently unavailable via Jitpack. Due to the error message

Tag or commit '1.7.0' not found. Rechecking.

I assume that this is because this project, other than upstream, does not have any releases defined. I'm not sure if you actually want to start defining releases already - if not, having a small note in the Get Started section of README.md mentioning that including this project currently doesn't work could be an alternative.

The path prefix to "api/v1" is currently hardcoded in MastodonClient.kt. This will be problematic once V2 endpoints need to be added, but is already an issue for the OAuth endpoints that aren't located under "/api".

The current workaround is to offer a separate postUrl(String, Parameter) method that interprets its string input as a full URL, whereas post(String, Parameter) interprets its input as additional path segments under "api/v1". Both the fact that the two methods have an identical signature and the fact that there's no check on whether the full URL even uses the same host as defined as instanceName can lead to issues down the line.

This could be solved by moving the full path to each endpoint out of MastodonClient and into each of its callers. At the same time, building the final URLs can be moved from doing it ourselves to using okHttp.HttpUrl and its builder throughout, which might prevent more bugs from happening.

I'm already working on the OkHttp part of #5, so I could tackle this in the process.

The following fields are currently missing in the Error entity class:

• error_description