From fbd7b771efde2bc364e0ec1f0847a7c9901db8b2 Mon Sep 17 00:00:00 2001 From: Kingkor Roy Tirtho Date: Thu, 14 Aug 2025 09:55:28 +0600 Subject: [PATCH] docs: add detailed documentation for BrowseEndpoint, CoreEndpoint, and SearchEndpoint --- .../developing-plugins/browse-endpoint.mdx | 48 ++++++++++++ .../docs/developing-plugins/core-endpoint.mdx | 74 +++++++++++++++++++ .../developing-plugins/search-endpoint.mdx | 59 +++++++++++++++ 3 files changed, 181 insertions(+) create mode 100644 website/src/content/docs/developing-plugins/browse-endpoint.mdx create mode 100644 website/src/content/docs/developing-plugins/core-endpoint.mdx create mode 100644 website/src/content/docs/developing-plugins/search-endpoint.mdx diff --git a/website/src/content/docs/developing-plugins/browse-endpoint.mdx b/website/src/content/docs/developing-plugins/browse-endpoint.mdx new file mode 100644 index 00000000..9861d02e --- /dev/null +++ b/website/src/content/docs/developing-plugins/browse-endpoint.mdx @@ -0,0 +1,48 @@ +--- +layout: "layouts/DocLayout.astro" +title: The BrowseEndpoint +description: "" +order: 10 +--- + +The BrowseEndpoint is used to fetch recommendations and catalogs of playlists, albums and artists. In the `src/segments/browse.ht` file you can find all the +required method definitions. + +```hetu_script +class BrowseEndpoint { + var client: HttpClient + + construct (this.client) + + fun sections({offset: int, limit: int}) { + // TODO: Implement method + } + + fun sectionItems(id: string, {offset: int, limit: int}) { + // TODO: Implement method + } +} +``` + +| Method | Description | Returns | +| ---------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | +| `sections()` | Returns the sections of the home page. | [`SpotubePaginationResponseObject`][SpotubePaginationResponseObject] of [`SpotubeBrowseSectionObject`][SpotubeBrowseSectionObject] of `Object` | +| `sectionItems()` | Returns the items of a specific section. | [`SpotubePaginationResponseObject`][SpotubePaginationResponseObject] of `Object` | + +> In `sectionItems()` The `id` it takes comes from `sections()`. It is basically used in an expanded screen to show the browse section items with pagination. +> +> For sections returned by `sections()` if `browseMore` is `true` that's when `sectionItems()` is used to fetch the items of that section. + +By the way, the `Object` can be any of the following types: + +- [`SpotubeFullPlaylistObject`][SpotubeFullPlaylistObject] +- [`SpotubeFullArtistObject`][SpotubeFullArtistObject] +- [`SpotubeFullAlbumObject`][SpotubeFullAlbumObject] + +{/* Urls */} +[SpotubePaginationResponseObject]: /models/spotube-pagination-response-object +[SpotubeBrowseSectionObject]: /models/spotube-browse-section-object +[SpotubeFullPlaylistObject]: /models/spotube-full-playlist-object +[SpotubeFullTrackObject]: /models/spotube-full-track-object +[SpotubeFullArtistObject]: /models/spotube-full-artist-object +[SpotubeFullAlbumObject]: /models/spotube-full-album-object diff --git a/website/src/content/docs/developing-plugins/core-endpoint.mdx b/website/src/content/docs/developing-plugins/core-endpoint.mdx new file mode 100644 index 00000000..5daedc29 --- /dev/null +++ b/website/src/content/docs/developing-plugins/core-endpoint.mdx @@ -0,0 +1,74 @@ +--- +layout: "layouts/DocLayout.astro" +title: The CoreEndpoint +description: "" +order: 11 +--- + +The CoreEndpoint is a special subclass which is used to check update and scrobbling and to get support text. In the `src/segments/core.ht` file you can find all the +required method definitions. + +```hetu_script +class CorePlugin { + var client: HttpClient + + construct (this.client) + + /// Checks for updates to the plugin. + /// [currentConfig] is just plugin.json's file content. + /// + /// If there's an update available, it will return a map of: + /// - [downloadUrl] -> direct download url to the new plugin.smplug file. + /// - [version] of the new plugin. + /// - [changelog] Optionally, a changelog for the update (markdown supported). + /// + /// If no update is available, it will return null. + fun checkUpdate(currentConfig: Map) -> Future { + // TODO: Check for updates + } + + /// Returns the support information for the plugin in Markdown or plain text. + /// Supports images and links. + get support -> string { + // TODO: Return support information + return "" + } + + /// Scrobble the provided details to the scrobbling service supported by the plugin. + /// "scrobbling" must be set as an ability in the plugin.json + /// [details] is a map containing the scrobble information, such as: + /// - [id] -> The unique identifier of the track. + /// - [title] -> The title of the track. + /// - [artists] -> List of artists + /// - [id] -> The unique identifier of the artist. + /// - [name] -> The name of the artist. + /// - [album] -> The album of the track + /// - [id] -> The unique identifier of the album. + /// - [name] -> The name of the album. + /// - [timestamp] -> The timestamp of the scrobble (optional). + /// - [duration_ms] -> The duration of the track in milliseconds (optional). + /// - [isrc] -> The ISRC code of the track (optional). + fun scrobble(details: Map) { + // TODO: Implement scrobbling + } +} +``` + +| Method | Description | Returns | +| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | +| `checkUpdate()` | Checks for updates to the plugin. | `Future` with a map containing `downloadUrl`, `version`, and optionally `changelog`. If no update is available, returns `null`. | +| `support` | Returns support information. | `string` containing the support information in Markdown or plain text. | +| `scrobble()` | [Scrobbles][scrobbling_wiki] the provided track details. This is only called if your plugin.json has scrobbling in the `abilities` field | `void` | + +> In the `checkUpdate()` method the `plugin.json`'s content will be passed as map. You can use that to check updates using the `version` field. +> +> Also, the `downloadUrl` it provides should be a direct binary download link (redirect is supported) for the `.smplug` file + +{/* Urls */} +[SpotubePaginationResponseObject]: /models/spotube-pagination-response-object +[SpotubeBrowseSectionObject]: /models/spotube-browse-section-object +[SpotubeFullPlaylistObject]: /models/spotube-full-playlist-object +[SpotubeFullTrackObject]: /models/spotube-full-track-object +[SpotubeFullArtistObject]: /models/spotube-full-artist-object +[SpotubeFullAlbumObject]: /models/spotube-full-album-object +[scrobbling_wiki]: https://en.wikipedia.org/wiki/Last.fm diff --git a/website/src/content/docs/developing-plugins/search-endpoint.mdx b/website/src/content/docs/developing-plugins/search-endpoint.mdx new file mode 100644 index 00000000..bc76d707 --- /dev/null +++ b/website/src/content/docs/developing-plugins/search-endpoint.mdx @@ -0,0 +1,59 @@ +--- +layout: "layouts/DocLayout.astro" +title: The SearchEndpoint +description: "" +order: 9 +--- + +The SearchEndpoint is used to fetch search playlist, tracks, album and artists. In the `src/segments/search.ht` file you can find all the +required method definitions. + +```hetu_script +class SearchEndpoint { + var client: HttpClient + + construct (this.client) + + get chips -> List { // Set + // can be tracks, playlists, artists, albums and all + return ["all", "tracks", "albums", "artists", "playlists"] + } + + fun all(query: string) { + // TODO: Implement method + } + + fun albums(query: string, {offset: int, limit: int}) { + // TODO: Implement method + } + + fun artists(query: string, {offset: int, limit: int}) { + // TODO: Implement method + } + + fun tracks(query: string, {offset: int, limit: int}) { + // TODO: Implement method + } + + fun playlists(query: string, {offset: int, limit: int}) { + // TODO: Implement method + } +} +``` + +| Method | Description | Returns | +| ------------- | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | +| `chips` | Returns the available search chips. | `List` | +| `all()` | Searches for all types of content. | [`SpotubeSearchResponseObject`][SpotubeSearchResponseObject] | +| `albums()` | Searches only for albums. | [`SpotubePaginationResponseObject`][SpotubePaginationResponseObject] of [`SpotubeFullAlbumObject`][SpotubeFullAlbumObject] | +| `artists()` | Searches only for artists. | [`SpotubePaginationResponseObject`][SpotubePaginationResponseObject] of [`SpotubeFullArtistObject`][SpotubeFullArtistObject] | +| `tracks()` | Searches only for tracks. | [`SpotubePaginationResponseObject`][SpotubePaginationResponseObject] of [`SpotubeFullTrackObject`][SpotubeFullTrackObject] | +| `playlists()` | Searches only for playlists. | [`SpotubePaginationResponseObject`][SpotubePaginationResponseObject] of [`SpotubeFullPlaylistObject`][SpotubeFullPlaylistObject] | + +{/* Urls */} +[SpotubePaginationResponseObject]: /models/spotube-pagination-response-object +[SpotubeSearchResponseObject]: /models/spotube-search-response-object +[SpotubeFullPlaylistObject]: /models/spotube-full-playlist-object +[SpotubeFullTrackObject]: /models/spotube-full-track-object +[SpotubeFullArtistObject]: /models/spotube-full-artist-object +[SpotubeFullAlbumObject]: /models/spotube-full-album-object