diff --git a/website/src/components/navigation/DocSideBar.astro b/website/src/components/navigation/DocSideBar.astro index 05892b80..c5a24823 100644 --- a/website/src/components/navigation/DocSideBar.astro +++ b/website/src/components/navigation/DocSideBar.astro @@ -58,7 +58,7 @@ const sections: [ ][] = [ ["Get Started", "get-started/", queryCollection], ["Developing Plugins", "developing-plugins/", queryCollection], - ["Models", "models/", queryCollection], + ["Reference", "reference/", queryCollection], // ["Design System", "design/", queryCollection], // ["Tailwind Components", "tailwind/", queryCollection], // ["Functional Components", "components/", queryMetaCollection], diff --git a/website/src/content/docs/developing-plugins/album-endpoint.mdx b/website/src/content/docs/developing-plugins/album-endpoint.mdx deleted file mode 100644 index 2d2ec3dd..00000000 --- a/website/src/content/docs/developing-plugins/album-endpoint.mdx +++ /dev/null @@ -1,48 +0,0 @@ ---- -layout: "layouts/DocLayout.astro" -title: The AlbumEndpoint -description: "" -order: 6 ---- - -The AlbumEndpoint is used to fetch album information and do album-related actions. In the `src/segments/album.ht` file you can find all the -required method definitions. - -```hetu_script -class AlbumEndpoint { - construct (this.client) - - fun getAlbum(id: string) { - // TODO: Implement method - } - - fun tracks(id: string, {offset: int, limit: int}) { - // TODO: Implement method - } - - fun releases({offset: int, limit: int}) { - // TODO: Implement method - } - - fun save(albumIds: List) { // List - // TODO: Implement method - } - - fun unsave(albumIds: List) { // List - // TODO: Implement method - } -} -``` - -| Method | Description | Returns | -| ------------ | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | -| `getAlbum()` | Fetches album information by ID. | [`SpotubeFullAlbumObject`][SpotubeFullAlbumObject] | -| `tracks()` | Fetches tracks of the specified album. Accepts an ID and optional pagination parameters. | [`SpotubePaginationResponseObject`][SpotubePaginationResponseObject] of [`SpotubeFullTrackObject`][SpotubeFullTrackObject] | -| `releases()` | Fetches new album releases user followed artists or globally | [`SpotubePaginationResponseObject`][SpotubePaginationResponseObject] of [`SpotubeFullAlbumObject`][SpotubeFullAlbumObject] | -| `save()` | Saves the specified albums. Accepts a list of album IDs. | `void` | -| `unsave()` | Removes the specified albums from saved albums. Accepts a list of album IDs. | `void` | - -{/* Urls */} -[SpotubePaginationResponseObject]: /docs/models/spotube-pagination-response-object -[SpotubeFullAlbumObject]: /docs/models/spotube-album-object#spotubefullalbumobject -[SpotubeFullTrackObject]: /docs/models/spotube-track-object diff --git a/website/src/content/docs/developing-plugins/artist-endpoint.mdx b/website/src/content/docs/developing-plugins/artist-endpoint.mdx deleted file mode 100644 index 7c74d802..00000000 --- a/website/src/content/docs/developing-plugins/artist-endpoint.mdx +++ /dev/null @@ -1,56 +0,0 @@ ---- -layout: "layouts/DocLayout.astro" -title: The ArtistEndpoint -description: "" -order: 7 ---- - -The ArtistEndpoint is used to fetch artist information and do artist-related actions. In the `src/segments/artist.ht` file you can find all the -required method definitions. - -```hetu_script -class ArtistEndpoint { - var client: HttpClient - - construct (this.client) - - fun getArtist(id: string) { - // TODO: Implement method - } - - fun related(id: string, {offset: int, limit: int}) { - // TODO: Implement method - } - - fun topTracks(id: string, {limit: int, offset: int}) { - // TODO: Implement method - } - - fun albums(id: string, {offset: int, limit: int}) { - // TODO: Implement method - } - - fun save(artistIds: List) { - // TODO: Implement method - } - - fun unsave(artistIds: List) { - // TODO: Implement method - } -} -``` - -| Method | Description | Returns | -| ------------- | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | -| `getArtist()` | Fetches artist information by ID. | [`SpotubeFullArtistObject`][SpotubeFullArtistObject] | -| `related()` | Fetches related artists based on the specified artist ID. Accepts optional pagination. | [`SpotubePaginationResponseObject`][SpotubePaginationResponseObject] of [`SpotubeFullArtistObject`][SpotubeFullArtistObject] | -| `topTracks()` | Fetches top tracks of the specified artist. Accepts optional pagination. | [`SpotubePaginationResponseObject`][SpotubePaginationResponseObject] of [`SpotubeFullTrackObject`][SpotubeFullTrackObject] | -| `albums()` | Fetches albums of the specified artist. Accepts optional pagination. | [`SpotubePaginationResponseObject`][SpotubePaginationResponseObject] of [`SpotubeFullAlbumObject`][SpotubeFullAlbumObject] | -| `save()` | Saves the specified artists. Accepts a list of artist IDs. | `void` | -| `unsave()` | Removes the specified artists from saved artists. Accepts a list of artist IDs. | `void` | - -{/* Urls */} -[SpotubePaginationResponseObject]: /docs/models/spotube-pagination-response-object -[SpotubeFullAlbumObject]: /docs/models/spotube-album-object#spotubefullalbumobject -[SpotubeFullArtistObject]: /docs/models/spotube-artist-object#spotubefullartistobject -[SpotubeFullTrackObject]: /docs/models/spotube-track-object diff --git a/website/src/content/docs/developing-plugins/auth-endpoint.mdx b/website/src/content/docs/developing-plugins/auth-endpoint.mdx deleted file mode 100644 index 9a7e6ebb..00000000 --- a/website/src/content/docs/developing-plugins/auth-endpoint.mdx +++ /dev/null @@ -1,72 +0,0 @@ ---- -layout: "layouts/DocLayout.astro" -title: The AuthEndpoint -description: "" -order: 3 ---- - -> If your plugin doesn't need authentication support, you can skip this section. - -In the `src/segments/auth.ht` file you can find all the required method definition. These are the necessary -methods Spotube calls in it's lifecycle. - -```hetu_script -class AuthEndpoint { - var client: HttpClient - final controller: StreamController - - get authStateStream -> Stream => controller.stream - - construct (this.client){ - controller = StreamController.broadcast() - } - - fun isAuthenticated() -> bool { - // TODO: Implement method - return false - } - - fun authenticate() -> Future { - // TODO: Implement method - } - - fun logout() -> Future { - // TODO: Implement method - } -} -``` - -For this specific endpoint, you may need `WebView` or `Forms` to get user inputs. The [`hetu_spotube_plugin`][hetu_spotube_plugin] provides -such APIs. - -> Learn more about it in the [Spotube Plugin API][spotube_plugin_api] section - -### The `.authStateStream` property - -The `AuthEndpoint.authStateStream` property is also necessary to notify Spotube about the authentication status. [`hetu_std`][hetu_std] is a built-in -module and it exports `StreamController` which basically 1:1 copy of the Dart's [StreamController][dart_stream_controller]. -If the status of authentication changes you need to add a new event using the `controller.add` -Following events are respected by Spotube: - -| Name | Description | -| ----------- | ------------------------------------------------------------ | -| `login` | When user successfully completes login | -| `logout` | When user logs out of the service | -| `recovered` | When user's cached/saved credentials are recovered from disk | -| `refreshed` | When user's session is refreshed | - -Example of adding a new authentication event: - -```hetu_script -controller.add({ type: "login" }.toJson()) -``` - -By the way, the event type is a `Map` in the Dart side, so make sure to always convert hetu_script's [structs into Maps][hetu_struct_into_map] - -{/* Urls */} -[hetu_script_import_export_docs]: https://hetu-script.github.io/docs/en-US/grammar/import/ -[hetu_spotube_plugin]: https://github.com/KRTirtho/hetu_spotube_plugin -[spotube_plugin_api]: / -[hetu_std]: https://github.com/hetu-community/hetu_std -[dart_stream_controller]: https://api.flutter.dev/flutter/dart-async/StreamController-class.html -[hetu_struct_into_map]: https://hetu-script.github.io/docs/en-US/api_reference/hetu/#struct diff --git a/website/src/content/docs/developing-plugins/browse-endpoint.mdx b/website/src/content/docs/developing-plugins/browse-endpoint.mdx deleted file mode 100644 index 70f31075..00000000 --- a/website/src/content/docs/developing-plugins/browse-endpoint.mdx +++ /dev/null @@ -1,48 +0,0 @@ ---- -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]: /docs/models/spotube-pagination-response-object -[SpotubeBrowseSectionObject]: /docs/models/spotube-browse-section-object -[SpotubeFullPlaylistObject]: /docs/models/spotube-playlist-object#spotubefullplaylistobject -[SpotubeFullTrackObject]: /docs/models/spotube-track-object -[SpotubeFullArtistObject]: /docs/models/spotube-artist-object#spotubefullartistobject -[SpotubeFullAlbumObject]: /docs/models/spotube-album-object#spotubefullalbumobject diff --git a/website/src/content/docs/developing-plugins/core-endpoint.mdx b/website/src/content/docs/developing-plugins/core-endpoint.mdx deleted file mode 100644 index 20f9a651..00000000 --- a/website/src/content/docs/developing-plugins/core-endpoint.mdx +++ /dev/null @@ -1,68 +0,0 @@ ---- -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 */} -[scrobbling_wiki]: https://en.wikipedia.org/wiki/Last.fm diff --git a/website/src/content/docs/developing-plugins/implementing-endpoints.mdx b/website/src/content/docs/developing-plugins/implementing-endpoints.mdx new file mode 100644 index 00000000..dd564995 --- /dev/null +++ b/website/src/content/docs/developing-plugins/implementing-endpoints.mdx @@ -0,0 +1,493 @@ +--- +layout: "layouts/DocLayout.astro" +title: Implementing Endpoints +description: "" +order: 2 +--- + +## AuthEndpoint + +> If your plugin doesn't need authentication support, you can skip this section. + +In the `src/segments/auth.ht` file you can find all the required method definition. These are the necessary +methods Spotube calls in it's lifecycle. + +```hetu_script +class AuthEndpoint { + var client: HttpClient + final controller: StreamController + + get authStateStream -> Stream => controller.stream + + construct (this.client){ + controller = StreamController.broadcast() + } + + fun isAuthenticated() -> bool { + // TODO: Implement method + return false + } + + fun authenticate() -> Future { + // TODO: Implement method + } + + fun logout() -> Future { + // TODO: Implement method + } +} +``` + +For this specific endpoint, you may need `WebView` or `Forms` to get user inputs. The [`hetu_spotube_plugin`][hetu_spotube_plugin] provides +such APIs. + +> Learn more about it in the [Spotube Plugin API][spotube_plugin_api] section + +### The `.authStateStream` property + +The `AuthEndpoint.authStateStream` property is also necessary to notify Spotube about the authentication status. [`hetu_std`][hetu_std] is a built-in +module and it exports `StreamController` which basically 1:1 copy of the Dart's [StreamController][dart_stream_controller]. +If the status of authentication changes you need to add a new event using the `controller.add` +Following events are respected by Spotube: + +| Name | Description | +| ----------- | ------------------------------------------------------------ | +| `login` | When user successfully completes login | +| `logout` | When user logs out of the service | +| `recovered` | When user's cached/saved credentials are recovered from disk | +| `refreshed` | When user's session is refreshed | + +Example of adding a new authentication event: + +```hetu_script +controller.add({ type: "login" }.toJson()) +``` + +By the way, the event type is a `Map` in the Dart side, so make sure to always convert hetu_script's [structs into Maps][hetu_struct_into_map] + +## UserEndpoint + +The UserEndpoint is used to fetch user information and manage user-related actions. +In the `src/segments/user.ht` file you can find all the required method definitions. These are the necessary +methods Spotube calls in its lifecycle. + +> Most of these methods should be just a mapping to an API call with minimum latency. Avoid calling plugin APIs like WebView or Forms +> in these methods. User interactions should be avoided here generally. + +```hetu_script +class UserEndpoint { + var client: HttpClient + + construct (this.client) + + fun me() { + // TODO: Implement method + } + + fun savedTracks({ offset: int, limit: int }) { + // TODO: Implement method + } + + fun savedPlaylists({ offset: int, limit: int }) { + // TODO: Implement method + } + + fun savedAlbums({ offset: int, limit: int }) { + // TODO: Implement method + } + + fun savedArtists({ offset: int, limit: int }) { + // TODO: Implement method + } + + fun isSavedPlaylist(playlistId: string) { // Future + // TODO: Implement method + } + + fun isSavedTracks(trackIds: List) { // Future> + // TODO: Implement method + } + + fun isSavedAlbums(albumIds: List) { // Future> + // TODO: Implement method + } + + fun isSavedArtists(artistIds: List) { // Future> + // TODO: Implement method + } +} +``` + +These methods are pretty self-explanatory. You need to implement them to fetch user information from your service. + +| Method | Description | Returns | +| ------------------- | ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------- | +| `me()` | Fetches the current user's information. | [`SpotubeUserObject`][SpotubeUserObject] | +| `savedTracks()` | Fetches the user's saved tracks with pagination support. | [`SpotubePaginationResponseObject`][SpotubePaginationResponseObject] of [`SpotubeFullTrackObject`][SpotubeFullTrackObject] | +| `savedPlaylists()` | Fetches the user's saved playlists with pagination support. | [`SpotubePaginationResponseObject`][SpotubePaginationResponseObject] of [`SpotubeFullPlaylistObject`][SpotubeFullPlaylistObject] | +| `savedAlbums()` | Fetches the user's saved albums with pagination support. | [`SpotubePaginationResponseObject`][SpotubePaginationResponseObject] of [`SpotubeFullAlbumObject`][SpotubeFullAlbumObject] | +| `savedArtists()` | Fetches the user's saved artists with pagination support. | [`SpotubePaginationResponseObject`][SpotubePaginationResponseObject] of [`SpotubeFullArtistObject`][SpotubeFullArtistObject] | +| `isSavedPlaylist()` | Checks if a playlist is saved by the user. Returns a `Future`. | `bool` | +| `isSavedTracks()` | Checks if tracks are saved by the user. Returns a `Future>`. | `List` (each boolean corresponds to a track ID) | +| `isSavedAlbums()` | Checks if albums are saved by the user. Returns a `Future>`. | `List` (each boolean corresponds to an album ID) | +| `isSavedArtists()` | Checks if artists are saved by the user. Returns a `Future>`. | `List` (each boolean corresponds to an artist ID) | + +> Note: The `isSavedTracks`, `isSavedAlbums`, and `isSavedArtists` methods accept a list of IDs and return a list of booleans +> indicating whether each item is saved by the user. The order of the booleans in the list corresponds to the order of the IDs +> in the input list. + +## TrackEndpoint + +The TrackEndpoint is used to fetch track information and do track-related actions. In the `src/segments/track.ht` file you can find all the +required method definitions. + +```hetu_script +class TrackEndpoint { + var client: HttpClient + + construct (this.client) + + fun getTrack(id: string) { + // TODO: Implement method + } + + fun save(trackIds: List) { // List + // TODO: Implement method + } + + fun unsave(trackIds: List) { // List + // TODO: Implement method + } + + fun radio(id: string) { + // TODO: Implement method + } +} +``` + +| Method | Description | Returns | +| ------------ | ------------------------------------------------------------------------------------ | -------------------------------------------------------- | +| `getTrack()` | Fetches track information by ID. | [SpotubeFullTrackObject][SpotubeFullTrackObject] | +| `save()` | Saves the specified tracks. Accepts a list of track IDs. | void | +| `unsave()` | Removes the specified tracks from saved tracks. Accepts a list of track IDs. | void | +| `radio()` | Fetches related tracks based on specified tracks. Try to return a List of 50 tracks. | [List\][SpotubeFullTrackObject] | + +{/* Urls */} + +## AlbumEndpoint + +The AlbumEndpoint is used to fetch album information and do album-related actions. In the `src/segments/album.ht` file you can find all the +required method definitions. + +```hetu_script +class AlbumEndpoint { + construct (this.client) + + fun getAlbum(id: string) { + // TODO: Implement method + } + + fun tracks(id: string, {offset: int, limit: int}) { + // TODO: Implement method + } + + fun releases({offset: int, limit: int}) { + // TODO: Implement method + } + + fun save(albumIds: List) { // List + // TODO: Implement method + } + + fun unsave(albumIds: List) { // List + // TODO: Implement method + } +} +``` + +| Method | Description | Returns | +| ------------ | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | +| `getAlbum()` | Fetches album information by ID. | [`SpotubeFullAlbumObject`][SpotubeFullAlbumObject] | +| `tracks()` | Fetches tracks of the specified album. Accepts an ID and optional pagination parameters. | [`SpotubePaginationResponseObject`][SpotubePaginationResponseObject] of [`SpotubeFullTrackObject`][SpotubeFullTrackObject] | +| `releases()` | Fetches new album releases user followed artists or globally | [`SpotubePaginationResponseObject`][SpotubePaginationResponseObject] of [`SpotubeFullAlbumObject`][SpotubeFullAlbumObject] | +| `save()` | Saves the specified albums. Accepts a list of album IDs. | `void` | +| `unsave()` | Removes the specified albums from saved albums. Accepts a list of album IDs. | `void` | + +## ArtistEndpoint + +The ArtistEndpoint is used to fetch artist information and do artist-related actions. In the `src/segments/artist.ht` file you can find all the +required method definitions. + +```hetu_script +class ArtistEndpoint { + var client: HttpClient + + construct (this.client) + + fun getArtist(id: string) { + // TODO: Implement method + } + + fun related(id: string, {offset: int, limit: int}) { + // TODO: Implement method + } + + fun topTracks(id: string, {limit: int, offset: int}) { + // TODO: Implement method + } + + fun albums(id: string, {offset: int, limit: int}) { + // TODO: Implement method + } + + fun save(artistIds: List) { + // TODO: Implement method + } + + fun unsave(artistIds: List) { + // TODO: Implement method + } +} +``` + +| Method | Description | Returns | +| ------------- | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | +| `getArtist()` | Fetches artist information by ID. | [`SpotubeFullArtistObject`][SpotubeFullArtistObject] | +| `related()` | Fetches related artists based on the specified artist ID. Accepts optional pagination. | [`SpotubePaginationResponseObject`][SpotubePaginationResponseObject] of [`SpotubeFullArtistObject`][SpotubeFullArtistObject] | +| `topTracks()` | Fetches top tracks of the specified artist. Accepts optional pagination. | [`SpotubePaginationResponseObject`][SpotubePaginationResponseObject] of [`SpotubeFullTrackObject`][SpotubeFullTrackObject] | +| `albums()` | Fetches albums of the specified artist. Accepts optional pagination. | [`SpotubePaginationResponseObject`][SpotubePaginationResponseObject] of [`SpotubeFullAlbumObject`][SpotubeFullAlbumObject] | +| `save()` | Saves the specified artists. Accepts a list of artist IDs. | `void` | +| `unsave()` | Removes the specified artists from saved artists. Accepts a list of artist IDs. | `void` | + +## PlaylistEndpoint + +The PlaylistEndpoint is used to fetch playlist information and do track-related actions. In the `src/segments/playlist.ht` file you can find all the +required method definitions. + +```hetu_script +class PlaylistEndpoint { + var client: HttpClient + + construct (this.client) + + fun getPlaylist(id: string) { + // TODO: Implement method + } + + fun tracks(id: string, { offset: int, limit: int }) { + // TODO: Implement method + } + + fun create(userId: string, { + name: string, + description: string, + public: bool, + collaborative: bool + }) { + // TODO: Implement method + } + + fun update(playlistId: string, { + name: string, + description: string, + public: bool, + collaborative: bool + }) { + // TODO: Implement method + } + + fun deletePlaylist(playlistId: string) { + // TODO: Implement method + } + + fun addTracks(playlistId: string, { trackIds: List, position: int }) { + // TODO: Implement method + } + + + fun removeTracks(playlistId: string, { trackIds: List }) { + // TODO: Implement method + } + + fun save(playlistId: string) { + // TODO: Implement method + } + + fun unsave(playlistId: string) { + // TODO: Implement method + } +} +``` + +| Method | Description | Returns | +| ---------------- | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | +| `getPlaylist` | Fetches a playlist by its ID. | [`SpotubeFullPlaylistObject`][SpotubeFullPlaylistObject] | +| `tracks` | Fetches tracks in a playlist. | [`SpotubePaginationResponseObject`][SpotubePaginationResponseObject] of [`SpotubeFullTrackObject`][SpotubeFullTrackObject] | +| `create` | Creates a new playlist and returns | [`SpotubeFullPlaylistObject`][SpotubeFullPlaylistObject] | +| `update` | Updates an existing playlist. | `void` | +| `deletePlaylist` | Deletes a playlist. | `void` | +| `addTracks` | Adds tracks to a playlist. | `void` | +| `removeTracks` | Removes tracks from a playlist. | `void` | +| `save` | Saves a playlist to the user's library. | `void` | +| `unsave` | Removes a playlist from the user's library. | `void` | + +## SearchEndpoint + +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] | + +## BrowseEndpoint + +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] + +## CoreEndpoint + +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 */} +[scrobbling_wiki]: https://en.wikipedia.org/wiki/Last.fm +[hetu_script_import_export_docs]: https://hetu-script.github.io/docs/en-US/grammar/import/ +[hetu_spotube_plugin]: https://github.com/KRTirtho/hetu_spotube_plugin +[spotube_plugin_api]: / +[hetu_std]: https://github.com/hetu-community/hetu_std +[dart_stream_controller]: https://api.flutter.dev/flutter/dart-async/StreamController-class.html +[hetu_struct_into_map]: https://hetu-script.github.io/docs/en-US/api_reference/hetu/#struct +[SpotubeUserObject]: /docs/reference/models#user +[SpotubePaginationResponseObject]: /docs/reference/models#pagination-response +[SpotubeFullAlbumObject]: /docs/reference/models#spotubefullalbumobject +[SpotubeFullArtistObject]: /docs/reference/models#spotubefullartistobject +[SpotubeFullTrackObject]: /docs/reference/models#track +[SpotubeFullPlaylistObject]: /docs/reference/models#spotubefullplaylistobject +[SpotubeSearchResponseObject]: /docs/reference/models#search-response +[SpotubeBrowseSectionObject]: /docs/reference/models#browse-section diff --git a/website/src/content/docs/developing-plugins/playlist-endpoint.mdx b/website/src/content/docs/developing-plugins/playlist-endpoint.mdx deleted file mode 100644 index 137f4a60..00000000 --- a/website/src/content/docs/developing-plugins/playlist-endpoint.mdx +++ /dev/null @@ -1,81 +0,0 @@ ---- -layout: "layouts/DocLayout.astro" -title: The PlaylistEndpoint -description: "" -order: 8 ---- - -The PlaylistEndpoint is used to fetch playlist information and do track-related actions. In the `src/segments/playlist.ht` file you can find all the -required method definitions. - -```hetu_script -class PlaylistEndpoint { - var client: HttpClient - - construct (this.client) - - fun getPlaylist(id: string) { - // TODO: Implement method - } - - fun tracks(id: string, { offset: int, limit: int }) { - // TODO: Implement method - } - - fun create(userId: string, { - name: string, - description: string, - public: bool, - collaborative: bool - }) { - // TODO: Implement method - } - - fun update(playlistId: string, { - name: string, - description: string, - public: bool, - collaborative: bool - }) { - // TODO: Implement method - } - - fun deletePlaylist(playlistId: string) { - // TODO: Implement method - } - - fun addTracks(playlistId: string, { trackIds: List, position: int }) { - // TODO: Implement method - } - - - fun removeTracks(playlistId: string, { trackIds: List }) { - // TODO: Implement method - } - - fun save(playlistId: string) { - // TODO: Implement method - } - - fun unsave(playlistId: string) { - // TODO: Implement method - } -} -``` - -| Method | Description | Returns | -| ---------------- | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | -| `getPlaylist` | Fetches a playlist by its ID. | [`SpotubeFullPlaylistObject`][SpotubeFullPlaylistObject] | -| `tracks` | Fetches tracks in a playlist. | [`SpotubePaginationResponseObject`][SpotubePaginationResponseObject] of [`SpotubeFullTrackObject`][SpotubeFullTrackObject] | -| `create` | Creates a new playlist and returns | [`SpotubeFullPlaylistObject`][SpotubeFullPlaylistObject] | -| `update` | Updates an existing playlist. | `void` | -| `deletePlaylist` | Deletes a playlist. | `void` | -| `addTracks` | Adds tracks to a playlist. | `void` | -| `removeTracks` | Removes tracks from a playlist. | `void` | -| `save` | Saves a playlist to the user's library. | `void` | -| `unsave` | Removes a playlist from the user's library. | `void` | - -{/* Urls */} -[SpotubePaginationResponseObject]: /docs/models/spotube-pagination-response-object -[SpotubeFullPlaylistObject]: /docs/models/spotube-playlist-object#spotubefullplaylistobject -[SpotubeFullTrackObject]: /docs/models/spotube-track-object diff --git a/website/src/content/docs/developing-plugins/search-endpoint.mdx b/website/src/content/docs/developing-plugins/search-endpoint.mdx deleted file mode 100644 index 4411aa77..00000000 --- a/website/src/content/docs/developing-plugins/search-endpoint.mdx +++ /dev/null @@ -1,59 +0,0 @@ ---- -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]: /docs/models/spotube-pagination-response-object -[SpotubeSearchResponseObject]: /docs/models/spotube-search-response-object -[SpotubeFullPlaylistObject]: /docs/models/spotube-playlist-object#spotubefullplaylistobject -[SpotubeFullTrackObject]: /docs/models/spotube-track-object -[SpotubeFullArtistObject]: /docs/models/spotube-artist-object#spotubefullartistobject -[SpotubeFullAlbumObject]: /docs/models/spotube-album-object#spotubefullalbumobject diff --git a/website/src/content/docs/developing-plugins/track-endpoint.mdx b/website/src/content/docs/developing-plugins/track-endpoint.mdx deleted file mode 100644 index d6e34695..00000000 --- a/website/src/content/docs/developing-plugins/track-endpoint.mdx +++ /dev/null @@ -1,43 +0,0 @@ ---- -layout: "layouts/DocLayout.astro" -title: The TrackEndpoint -description: "" -order: 5 ---- - -The TrackEndpoint is used to fetch track information and do track-related actions. In the `src/segments/track.ht` file you can find all the -required method definitions. - -```hetu_script -class TrackEndpoint { - var client: HttpClient - - construct (this.client) - - fun getTrack(id: string) { - // TODO: Implement method - } - - fun save(trackIds: List) { // List - // TODO: Implement method - } - - fun unsave(trackIds: List) { // List - // TODO: Implement method - } - - fun radio(id: string) { - // TODO: Implement method - } -} -``` - -| Method | Description | Returns | -| ------------ | ------------------------------------------------------------------------------------ | -------------------------------------------------------- | -| `getTrack()` | Fetches track information by ID. | [SpotubeFullTrackObject][SpotubeFullTrackObject] | -| `save()` | Saves the specified tracks. Accepts a list of track IDs. | void | -| `unsave()` | Removes the specified tracks from saved tracks. Accepts a list of track IDs. | void | -| `radio()` | Fetches related tracks based on specified tracks. Try to return a List of 50 tracks. | [List\][SpotubeFullTrackObject] | - -{/* Urls */} -[SpotubeFullTrackObject]: /docs/models/spotube-track-object diff --git a/website/src/content/docs/developing-plugins/user-endpoint.mdx b/website/src/content/docs/developing-plugins/user-endpoint.mdx deleted file mode 100644 index 4b8efb33..00000000 --- a/website/src/content/docs/developing-plugins/user-endpoint.mdx +++ /dev/null @@ -1,83 +0,0 @@ ---- -layout: "layouts/DocLayout.astro" -title: The UserEndpoint -description: "" -order: 4 ---- - -The UserEndpoint is used to fetch user information and manage user-related actions. -In the `src/segments/user.ht` file you can find all the required method definitions. These are the necessary -methods Spotube calls in its lifecycle. - -> Most of these methods should be just a mapping to an API call with minimum latency. Avoid calling plugin APIs like WebView or Forms -> in these methods. User interactions should be avoided here generally. - -```hetu_script -class UserEndpoint { - var client: HttpClient - - construct (this.client) - - fun me() { - // TODO: Implement method - } - - fun savedTracks({ offset: int, limit: int }) { - // TODO: Implement method - } - - fun savedPlaylists({ offset: int, limit: int }) { - // TODO: Implement method - } - - fun savedAlbums({ offset: int, limit: int }) { - // TODO: Implement method - } - - fun savedArtists({ offset: int, limit: int }) { - // TODO: Implement method - } - - fun isSavedPlaylist(playlistId: string) { // Future - // TODO: Implement method - } - - fun isSavedTracks(trackIds: List) { // Future> - // TODO: Implement method - } - - fun isSavedAlbums(albumIds: List) { // Future> - // TODO: Implement method - } - - fun isSavedArtists(artistIds: List) { // Future> - // TODO: Implement method - } -} -``` - -These methods are pretty self-explanatory. You need to implement them to fetch user information from your service. - -| Method | Description | Returns | -| ------------------- | ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------- | -| `me()` | Fetches the current user's information. | [`SpotubeUserObject`][SpotubeUserObject] | -| `savedTracks()` | Fetches the user's saved tracks with pagination support. | [`SpotubePaginationResponseObject`][SpotubePaginationResponseObject] of [`SpotubeFullTrackObject`][SpotubeFullTrackObject] | -| `savedPlaylists()` | Fetches the user's saved playlists with pagination support. | [`SpotubePaginationResponseObject`][SpotubePaginationResponseObject] of [`SpotubeFullPlaylistObject`][SpotubeFullPlaylistObject] | -| `savedAlbums()` | Fetches the user's saved albums with pagination support. | [`SpotubePaginationResponseObject`][SpotubePaginationResponseObject] of [`SpotubeFullAlbumObject`][SpotubeFullAlbumObject] | -| `savedArtists()` | Fetches the user's saved artists with pagination support. | [`SpotubePaginationResponseObject`][SpotubePaginationResponseObject] of [`SpotubeFullArtistObject`][SpotubeFullArtistObject] | -| `isSavedPlaylist()` | Checks if a playlist is saved by the user. Returns a `Future`. | `bool` | -| `isSavedTracks()` | Checks if tracks are saved by the user. Returns a `Future>`. | `List` (each boolean corresponds to a track ID) | -| `isSavedAlbums()` | Checks if albums are saved by the user. Returns a `Future>`. | `List` (each boolean corresponds to an album ID) | -| `isSavedArtists()` | Checks if artists are saved by the user. Returns a `Future>`. | `List` (each boolean corresponds to an artist ID) | - -> Note: The `isSavedTracks`, `isSavedAlbums`, and `isSavedArtists` methods accept a list of IDs and return a list of booleans -> indicating whether each item is saved by the user. The order of the booleans in the list corresponds to the order of the IDs -> in the input list. - -{/* Links */} -[SpotubeUserObject]: /docs/models/spotube-user-object -[SpotubePaginationResponseObject]: /docs/models/spotube-pagination-response-object -[SpotubeFullTrackObject]: /docs/models/spotube-track-object -[SpotubeFullPlaylistObject]: /docs/models/spotube-playlist-object#spotubefullplaylistobject -[SpotubeFullAlbumObject]: /docs/models/spotube-album-object#spotubefullalbumobject -[SpotubeFullArtistObject]: /docs/models/spotube-artist-object#spotubefullartistobject diff --git a/website/src/content/docs/models/spotube-album-object.mdx b/website/src/content/docs/models/spotube-album-object.mdx deleted file mode 100644 index 29197e90..00000000 --- a/website/src/content/docs/models/spotube-album-object.mdx +++ /dev/null @@ -1,42 +0,0 @@ ---- -layout: "layouts/DocLayout.astro" -title: Album -description: Different types of album objects used in Spotube. -order: 3 ---- - -### SpotubeSimpleAlbumObject - -Following is the structure of the `SpotubeAlbumObject`: - -| Property | Type | -| ----------- | ---------------------------------------------------------------- | -| id | `string` | -| name | `string` | -| externalUri | `string` | -| images | List of [`SpotubeImageObject`][SpotubeImageObject] | -| albumType | `album`, `single` or `compilation` | -| artists | List of [`SpotubeSimpleArtistObject`][SpotubeSimpleArtistObject] | -| releaseDate | `string` (YYYY-MM-DD format) or `null` | - -{/* Urls */} - -### SpotubeFullAlbumObject - -Following is the structure of the `SpotubeFullAlbumObject`: - -| Property | Type | -| ----------- | ---------------------------------------------------------------- | -| id | `string` | -| name | `string` | -| externalUri | `string` | -| images | List of [`SpotubeImageObject`][SpotubeImageObject] | -| albumType | `album`, `single` or `compilation` | -| artists | List of [`SpotubeSimpleArtistObject`][SpotubeSimpleArtistObject] | -| releaseDate | `string` (YYYY-MM-DD format) | -| totalTracks | `number` | -| recordLabel | `string` or `null` | - -{/* Urls */} -[SpotubeImageObject]: /docs/models/spotube-image-object -[SpotubeSimpleArtistObject]: /docs/models/spotube-artist-objects#spotubesimpleartistobject diff --git a/website/src/content/docs/models/spotube-artist-object.mdx b/website/src/content/docs/models/spotube-artist-object.mdx deleted file mode 100644 index ab1716db..00000000 --- a/website/src/content/docs/models/spotube-artist-object.mdx +++ /dev/null @@ -1,33 +0,0 @@ ---- -layout: "layouts/DocLayout.astro" -title: Artist -description: Different types of artist objects used in Spotube. -order: 2 ---- - -### SpotubeSimpleArtistObject - -Following is the structure of the `SpotubeArtistObject`: - -| Property | Type | -| ----------- | ------------------------------------------------------------ | -| id | `string` | -| name | `string` | -| externalUri | `string` | -| images | List of [`SpotubeImageObject`][SpotubeImageObject] or `null` | - -### SpotubeFullArtistObject - -Following is the structure of the `SpotubeFullArtistObject`: - -| Property | Type | -| ----------- | ----------------------------------------------------- | -| id | `string` | -| name | `string` | -| externalUri | `string` | -| images | List of [`SpotubeImageObject`][SpotubeImageObject] or | -| followers | `number` | -| genres | List of `string` or `null` | - -{/* Urls */} -[SpotubeImageObject]: /docs/models/spotube-image-object diff --git a/website/src/content/docs/models/spotube-browse-section-object.mdx b/website/src/content/docs/models/spotube-browse-section-object.mdx deleted file mode 100644 index 29368605..00000000 --- a/website/src/content/docs/models/spotube-browse-section-object.mdx +++ /dev/null @@ -1,27 +0,0 @@ ---- -layout: "layouts/DocLayout.astro" -title: Browse Section -description: "" -order: 7 ---- - -Following is the structure of `SpotubeBrowseSectionObject`: - -| Property | Type | -| ----------- | ---------------- | -| id | `string` | -| title | `string` | -| externalUri | `string` | -| browseMore | `boolean` | -| items | List of `Object` | - -The `items` property array can contain multiple type of `Object` in it but it will always be - -- [`SpotubeFullPlaylistObject`][SpotubeFullPlaylistObject] -- [`SpotubeFullAlbumObject`][SpotubeFullAlbumObject] -- [`SpotubeFullArtistObject`][SpotubeFullArtistObject] - -{/* Urls */} -[SpotubeFullPlaylistObject]: /docs/models/spotube-playlist-object#spotubefullplaylistobject -[SpotubeFullAlbumObject]: /docs/models/spotube-album-object#spotubefullalbumobject -[SpotubeFullArtistObject]: /docs/models/spotube-artist-object#spotubefullartistobject diff --git a/website/src/content/docs/models/spotube-image-object.mdx b/website/src/content/docs/models/spotube-image-object.mdx deleted file mode 100644 index 665e5d0a..00000000 --- a/website/src/content/docs/models/spotube-image-object.mdx +++ /dev/null @@ -1,14 +0,0 @@ ---- -layout: "layouts/DocLayout.astro" -title: Image -description: How images are represented in Spotube. -order: 0 ---- - -Following is the structure of the `SpotubeImageObject`: - -| Property | Type | -| -------- | --------------- | -| width | `int` or `null` | -| height | `int` or `null` | -| url | `string` | diff --git a/website/src/content/docs/models/spotube-pagination-response-object.mdx b/website/src/content/docs/models/spotube-pagination-response-object.mdx deleted file mode 100644 index a5efebc3..00000000 --- a/website/src/content/docs/models/spotube-pagination-response-object.mdx +++ /dev/null @@ -1,18 +0,0 @@ ---- -layout: "layouts/DocLayout.astro" -title: Pagination Response -description: "" -order: 8 ---- - -`SpotubePaginationResponseObject` is generic model. The `items` property can contain any type of `Object` in it. - -This is the structure of `SpotubePaginationResponseObject`: - -| Property | Type | -| ---------- | ----------------------------------------------- | -| limit | `number` | -| nextOffset | `number` or `null` | -| total | `number` | -| hasMore | `boolean` | -| items | List of generic type `T` which extends `Object` | diff --git a/website/src/content/docs/models/spotube-playlist-object.mdx b/website/src/content/docs/models/spotube-playlist-object.mdx deleted file mode 100644 index 3783e596..00000000 --- a/website/src/content/docs/models/spotube-playlist-object.mdx +++ /dev/null @@ -1,40 +0,0 @@ ---- -layout: "layouts/DocLayout.astro" -title: Playlist -description: Different types of playlist objects used in Spotube. -order: 5 ---- - -### SpotubeSimplePlaylistObject - -Following is the structure of the `SpotubeSimplePlaylistObject`: - -| Property | Type | -| ----------- | ------------------------------------------------------------ | -| id | `string` | -| name | `string` | -| description | `string` | -| externalUri | `string` | -| images | List of [`SpotubeImageObject`][SpotubeImageObject] or `null` | -| owner | [`SpotubeUserObject`][SpotubeUserObject] | - -### SpotubeFullPlaylistObject - -Following is the structure of the `SpotubeFullPlaylistObject`: - -| Property | Type | -| ------------- | ------------------------------------------------------------ | -| id | `string` | -| name | `string` | -| description | `string` | -| externalUri | `string` | -| images | List of [`SpotubeImageObject`][SpotubeImageObject] or `null` | -| owner | [`SpotubeUserObject`][SpotubeUserObject] | -| collaborators | List of [`SpotubeUserObject`][SpotubeUserObject] or `null` | -| collaborative | `boolean` | -| public | `boolean` | - -{/* Urls */} - -[SpotubeImageObject]: /docs/models/spotube-image-object -[SpotubeUserObject]: /docs/models/spotube-simple-user-object diff --git a/website/src/content/docs/models/spotube-search-response-object.mdx b/website/src/content/docs/models/spotube-search-response-object.mdx deleted file mode 100644 index efe51a26..00000000 --- a/website/src/content/docs/models/spotube-search-response-object.mdx +++ /dev/null @@ -1,21 +0,0 @@ ---- -layout: "layouts/DocLayout.astro" -title: Search Response -description: "" -order: 6 ---- - -Following is the structure of the `SpotubeSearchResponseObject`: - -| Property | Type | -| --------- | -------------------------------------------------------------------- | -| albums | List of [`SpotubeSimpleAlbumObject`][SpotubeSimpleAlbumObject] | -| artists | List of [`SpotubeFullArtistObject`][SpotubeFullArtistObject] | -| playlists | List of [`SpotubeSimplePlaylistObject`][SpotubeSimplePlaylistObject] | -| tracks | List of [`SpotubeFullTrackObject`][SpotubeFullTrackObject] | - -{/* Urls */} -[SpotubeSimpleAlbumObject]: /docs/models/spotube-album-object#spotubesimplealbumobject -[SpotubeFullArtistObject]: /docs/models/spotube-artist-object#spotubefullartistobject -[SpotubeSimplePlaylistObject]: /docs/models/spotube-playlist-object#spotubesimpleplaylistobject -[SpotubeFullTrackObject]: /docs/models/spotube-track-object diff --git a/website/src/content/docs/models/spotube-track-object.mdx b/website/src/content/docs/models/spotube-track-object.mdx deleted file mode 100644 index 3e4d8b92..00000000 --- a/website/src/content/docs/models/spotube-track-object.mdx +++ /dev/null @@ -1,27 +0,0 @@ ---- -layout: "layouts/DocLayout.astro" -title: Track -description: "" -order: 4 ---- - -Following is the structure of the `SpotubeFullTrackObject`: - -| Property | Type | -| ---------------------------- | ---------------------------------------------------------------- | -| id | `string` | -| name | `string` | -| externalUri | `string` | -| artists | List of [`SpotubeSimpleArtistObject`][SpotubeSimpleArtistObject] | -| album | [`SpotubeSimpleAlbumObject`][SpotubeSimpleAlbumObject] | -| durationMs (in milliseconds) | `number` | -| explicit | `boolean` | -| [isrc][isrc_wiki] | `string` | - -> `isrc` stands for International Standard Recording Code, which is a unique identifier for tracks. -> It is used to identify recordings and is often used in music distribution and royalty collection. The format is typically a 12-character alphanumeric code. - -{/* Urls */} -[SpotubeSimpleArtistObject]: /docs/models/spotube-artist-objects#spotubesimpleartistobject -[SpotubeSimpleAlbumObject]: /docs/models/spotube-album-object#spotubesimplealbumobject -[isrc_wiki]: https://en.wikipedia.org/wiki/International_Standard_Recording_Code diff --git a/website/src/content/docs/models/spotube-user-object.mdx b/website/src/content/docs/models/spotube-user-object.mdx deleted file mode 100644 index 9cd32f25..00000000 --- a/website/src/content/docs/models/spotube-user-object.mdx +++ /dev/null @@ -1,20 +0,0 @@ ---- -layout: "layouts/DocLayout.astro" -title: User -description: "" -order: 1 ---- - -Structure of the SpotubeUserObject, which is used to represent a user in Spotube returned by Spotube Plugins. - -| Property | Type | -| ----------- | -------------------------------------------------- | -| id | `string` | -| name | `string` | -| externalUri | `string` | -| images | List of [`SpotubeImageObject`][SpotubeImageObject] | - -> `externalUri` is a URL that points to the user's profile on the external service (e.g. Listenbrainz) - -{/* Urls */} -[SpotubeImageObject]: /docs/models/spotube-image-object diff --git a/website/src/content/docs/reference/models.mdx b/website/src/content/docs/reference/models.mdx new file mode 100644 index 00000000..8e29bb6c --- /dev/null +++ b/website/src/content/docs/reference/models.mdx @@ -0,0 +1,190 @@ +--- +layout: "layouts/DocLayout.astro" +title: Plugin Models +description: "Different types of objects used in Spotube." +order: 0 +--- + +## Image + +Following is the structure of the `SpotubeImageObject`: + +| Property | Type | +| -------- | --------------- | +| width | `int` or `null` | +| height | `int` or `null` | +| url | `string` | + +## User + +Structure of the `SpotubeUserObject`, which is used to represent a user in Spotube returned by Spotube Plugins. + +| Property | Type | +| ----------- | -------------------------------------------------- | +| id | `string` | +| name | `string` | +| externalUri | `string` | +| images | List of [`SpotubeImageObject`][SpotubeImageObject] | + +> `externalUri` is a URL that points to the user's profile on the external service (e.g. Listenbrainz) + +## Artist + +### SpotubeSimpleArtistObject + +Following is the structure of the `SpotubeArtistObject`: + +| Property | Type | +| ----------- | ------------------------------------------------------------ | +| id | `string` | +| name | `string` | +| externalUri | `string` | +| images | List of [`SpotubeImageObject`][SpotubeImageObject] or `null` | + +### SpotubeFullArtistObject + +Following is the structure of the `SpotubeFullArtistObject`: + +| Property | Type | +| ----------- | ----------------------------------------------------- | +| id | `string` | +| name | `string` | +| externalUri | `string` | +| images | List of [`SpotubeImageObject`][SpotubeImageObject] or | +| followers | `number` | +| genres | List of `string` or `null` | + +## Album + +### SpotubeSimpleAlbumObject + +Following is the structure of the `SpotubeAlbumObject`: + +| Property | Type | +| ----------- | ---------------------------------------------------------------- | +| id | `string` | +| name | `string` | +| externalUri | `string` | +| images | List of [`SpotubeImageObject`][SpotubeImageObject] | +| albumType | `album`, `single` or `compilation` | +| artists | List of [`SpotubeSimpleArtistObject`][SpotubeSimpleArtistObject] | +| releaseDate | `string` (YYYY-MM-DD format) or `null` | + +### SpotubeFullAlbumObject + +Following is the structure of the `SpotubeFullAlbumObject`: + +| Property | Type | +| ----------- | ---------------------------------------------------------------- | +| id | `string` | +| name | `string` | +| externalUri | `string` | +| images | List of [`SpotubeImageObject`][SpotubeImageObject] | +| albumType | `album`, `single` or `compilation` | +| artists | List of [`SpotubeSimpleArtistObject`][SpotubeSimpleArtistObject] | +| releaseDate | `string` (YYYY-MM-DD format) | +| totalTracks | `number` | +| recordLabel | `string` or `null` | + +## Track + +Following is the structure of the `SpotubeFullTrackObject`: + +| Property | Type | +| ---------------------------- | ---------------------------------------------------------------- | +| id | `string` | +| name | `string` | +| externalUri | `string` | +| artists | List of [`SpotubeSimpleArtistObject`][SpotubeSimpleArtistObject] | +| album | [`SpotubeSimpleAlbumObject`][SpotubeSimpleAlbumObject] | +| durationMs (in milliseconds) | `number` | +| explicit | `boolean` | +| [isrc][isrc_wiki] | `string` | + +> `isrc` stands for International Standard Recording Code, which is a unique identifier for tracks. +> It is used to identify recordings and is often used in music distribution and royalty collection. The format is typically a 12-character alphanumeric code. + +## Playlist + +### SpotubeSimplePlaylistObject + +Following is the structure of the `SpotubeSimplePlaylistObject`: + +| Property | Type | +| ----------- | ------------------------------------------------------------ | +| id | `string` | +| name | `string` | +| description | `string` | +| externalUri | `string` | +| images | List of [`SpotubeImageObject`][SpotubeImageObject] or `null` | +| owner | [`SpotubeUserObject`][SpotubeUserObject] | + +### SpotubeFullPlaylistObject + +Following is the structure of the `SpotubeFullPlaylistObject`: + +| Property | Type | +| ------------- | ------------------------------------------------------------ | +| id | `string` | +| name | `string` | +| description | `string` | +| externalUri | `string` | +| images | List of [`SpotubeImageObject`][SpotubeImageObject] or `null` | +| owner | [`SpotubeUserObject`][SpotubeUserObject] | +| collaborators | List of [`SpotubeUserObject`][SpotubeUserObject] or `null` | +| collaborative | `boolean` | +| public | `boolean` | + +## Search Response + +Following is the structure of the `SpotubeSearchResponseObject`: + +| Property | Type | +| --------- | -------------------------------------------------------------------- | +| albums | List of [`SpotubeSimpleAlbumObject`][SpotubeSimpleAlbumObject] | +| artists | List of [`SpotubeFullArtistObject`][SpotubeFullArtistObject] | +| playlists | List of [`SpotubeSimplePlaylistObject`][SpotubeSimplePlaylistObject] | +| tracks | List of [`SpotubeFullTrackObject`][SpotubeFullTrackObject] | + +## Browse Section + +Following is the structure of `SpotubeBrowseSectionObject`: + +| Property | Type | +| ----------- | ---------------- | +| id | `string` | +| title | `string` | +| externalUri | `string` | +| browseMore | `boolean` | +| items | List of `Object` | + +The `items` property array can contain multiple type of `Object` in it but it will always be + +- [`SpotubeFullPlaylistObject`][SpotubeFullPlaylistObject] +- [`SpotubeFullAlbumObject`][SpotubeFullAlbumObject] +- [`SpotubeFullArtistObject`][SpotubeFullArtistObject] + +## Pagination Response + +`SpotubePaginationResponseObject` is generic model. The `items` property can contain any type of `Object` in it. + +This is the structure of `SpotubePaginationResponseObject`: + +| Property | Type | +| ---------- | ----------------------------------------------- | +| limit | `number` | +| nextOffset | `number` or `null` | +| total | `number` | +| hasMore | `boolean` | +| items | List of generic type `T` which extends `Object` | + +[isrc_wiki]: https://en.wikipedia.org/wiki/International_Standard_Recording_Code +[SpotubeImageObject]: /docs/reference/models#image +[SpotubeSimpleArtistObject]: /docs/reference/models#spotubesimpleartistobject +[SpotubeSimpleAlbumObject]: /docs/reference/models#spotubesimplealbumobject +[SpotubeUserObject]: /docs/reference/models#user +[SpotubeFullArtistObject]: /docs/reference/models#spotubefullartistobject +[SpotubeSimplePlaylistObject]: /docs/reference/models#spotubesimpleplaylistobject +[SpotubeFullTrackObject]: /docs/reference/models#track +[SpotubeFullPlaylistObject]: /docs/reference/models#spotubefullplaylistobject +[SpotubeFullAlbumObject]: /docs/reference/models#spotubefullalbumobject