rockbox

Rockbox Gleam SDK — pipe-friendly client for the rockboxd GraphQL API.

import rockbox
import rockbox/playback

pub fn main() {
  let client = rockbox.connect()

  let assert Ok(track) = playback.current_track(client)
  let assert Ok(_) = playback.pause(client)
}

Customise the connection with the builder:

let client =
  rockbox.new()
  |> rockbox.host("rockbox.local")
  |> rockbox.port(8080)
  |> rockbox.connect

Types

Builder

opaque </>

A fluent builder used to configure a Client.

Construct with new, override defaults with host / port / url, then call connect (or build, the alias) to get a Client.

pub opaque type Builder

Client

opaque </>

A configured client. Hand it to any of the per-domain API modules:

playback.play(client, 0, 0)
library.search(client, "miles davis")

pub opaque type Client

Values

at

</>

pub fn at(host h: String, port p: Int) -> Client

Shortcut for new() |> host(host) |> port(port) |> connect().

build

</>

pub fn build(builder: Builder) -> Client

Alias for connect. Use whichever name reads better in your code.

connect

</>

pub fn connect(builder: Builder) -> Client

Finalise the builder and return a usable Client.

default_client

</>

pub fn default_client() -> Client

Shortcut for new() |> connect() — a client pointed at localhost:6062.

execute

</>

pub fn execute(
  client: Client,
  gql: String,
  variables: json.Json,
) -> Result(Nil, error.Error)

Like query but discards the response body — handy for fire-and-forget mutations that return a boolean status flag you don’t care about.

host

</>

pub fn host(builder: Builder, value: String) -> Builder

Override the hostname (default "localhost"). Ignored if url is set.

http_url

</>

pub fn http_url(client: Client) -> String

Return the underlying GraphQL HTTP URL. Useful for diagnostics & tests.

new

</>

pub fn new() -> Builder

Start a new client builder with sensible defaults (localhost:6062).

port

</>

pub fn port(builder: Builder, value: Int) -> Builder

Override the port (default 6062). Ignored if url is set.

query

</>

pub fn query(
  client: Client,
  gql: String,
  variables: json.Json,
  decoder: decode.Decoder(t),
) -> Result(t, error.Error)

Run a raw GraphQL operation against the server, decoding the data field with the supplied decoder. Useful if you need an endpoint the SDK doesn’t expose directly yet.

import gleam/dynamic/decode
import gleam/json

let decoder = {
  use version <- decode.field("rockboxVersion", decode.string)
  decode.success(version)
}

let assert Ok(version) =
  client
  |> rockbox.query("query { rockboxVersion }", json.object([]), decoder)

url

</>

pub fn url(builder: Builder, value: String) -> Builder

Override the full GraphQL HTTP URL. Takes precedence over host / port.