mirror of
https://github.com/KRTirtho/spotube.git
synced 2025-09-12 23:45:18 +00:00
docs: merge some endpoints together to reduce too much elements on the side bar
This commit is contained in:
Kingkor Roy Tirtho
parent
032309a2c6
commit
0e34057794
@ -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],
|
||||
|
||||
@ -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<String>
|
||||
// TODO: Implement method
|
||||
}
|
||||
|
||||
fun unsave(albumIds: List) { // List<String>
|
||||
// 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
|
||||
@ -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
|
||||
@ -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<String, dynamic>` 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
|
||||
@ -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
|
||||
@ -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
|
||||
@ -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<String, dynamic>` 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<bool>
|
||||
// TODO: Implement method
|
||||
}
|
||||
|
||||
fun isSavedTracks(trackIds: List) { // Future<List<bool>>
|
||||
// TODO: Implement method
|
||||
}
|
||||
|
||||
fun isSavedAlbums(albumIds: List) { // Future<List<bool>>
|
||||
// TODO: Implement method
|
||||
}
|
||||
|
||||
fun isSavedArtists(artistIds: List) { // Future<List<bool>>
|
||||
// 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>`. | `bool` |
|
||||
| `isSavedTracks()` | Checks if tracks are saved by the user. Returns a `Future<List<bool>>`. | `List<bool>` (each boolean corresponds to a track ID) |
|
||||
| `isSavedAlbums()` | Checks if albums are saved by the user. Returns a `Future<List<bool>>`. | `List<bool>` (each boolean corresponds to an album ID) |
|
||||
| `isSavedArtists()` | Checks if artists are saved by the user. Returns a `Future<List<bool>>`. | `List<bool>` (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<String>
|
||||
// TODO: Implement method
|
||||
}
|
||||
|
||||
fun unsave(trackIds: List) { // List<String>
|
||||
// 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\>][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<String>
|
||||
// TODO: Implement method
|
||||
}
|
||||
|
||||
fun unsave(albumIds: List) { // List<String>
|
||||
// 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<string>
|
||||
// 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<string>` |
|
||||
| `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
|
||||
@ -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
|
||||
@ -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<string>
|
||||
// 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<string>` |
|
||||
| `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
|
||||
@ -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<String>
|
||||
// TODO: Implement method
|
||||
}
|
||||
|
||||
fun unsave(trackIds: List) { // List<String>
|
||||
// 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\>][SpotubeFullTrackObject] |
|
||||
|
||||
{/* Urls */}
|
||||
[SpotubeFullTrackObject]: /docs/models/spotube-track-object
|
||||
@ -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<bool>
|
||||
// TODO: Implement method
|
||||
}
|
||||
|
||||
fun isSavedTracks(trackIds: List) { // Future<List<bool>>
|
||||
// TODO: Implement method
|
||||
}
|
||||
|
||||
fun isSavedAlbums(albumIds: List) { // Future<List<bool>>
|
||||
// TODO: Implement method
|
||||
}
|
||||
|
||||
fun isSavedArtists(artistIds: List) { // Future<List<bool>>
|
||||
// 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>`. | `bool` |
|
||||
| `isSavedTracks()` | Checks if tracks are saved by the user. Returns a `Future<List<bool>>`. | `List<bool>` (each boolean corresponds to a track ID) |
|
||||
| `isSavedAlbums()` | Checks if albums are saved by the user. Returns a `Future<List<bool>>`. | `List<bool>` (each boolean corresponds to an album ID) |
|
||||
| `isSavedArtists()` | Checks if artists are saved by the user. Returns a `Future<List<bool>>`. | `List<bool>` (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
|
||||
@ -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
|
||||
@ -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
|
||||
@ -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
|
||||
@ -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` |
|
||||
@ -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` |
|
||||
@ -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
|
||||
@ -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
|
||||
@ -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
|
||||
@ -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
|
||||
190
website/src/content/docs/reference/models.mdx
Normal file
190
website/src/content/docs/reference/models.mdx
Normal file
@ -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
|
||||
Loading…
Reference in New Issue
Block a user