rocksky - v1.5.1

rocksky/client

Rocksky SDK for Gleam.

Typed externals over the rocksky_erl NIF package (the shared Rust core, rocksky-sdk): AppView reads, record writes (scrobble, like, follow, shout), and the identity hashes shared across every Rocksky SDK.

Reads use the default AppView (https://api.rocksky.app); the *_at variants take a custom base URL. Envelope calls return Dynamic — an {ok, value} / {error, message} tuple with binary-keyed maps (the wire shape); decode with gleam/dynamic.

Types

Agent

</>

An opaque authenticated-agent handle (a NIF resource freed by the BEAM GC).

pub type Agent =
  dynamic.Dynamic

Interval

</>

A typed date window for the top_*_interval charts.

pub type Interval {
  AllTime
  LastDays(Int)
  LastWeeks(Int)
  LastMonths(Int)
  LastYears(Int)
  Range(start: String, end: String)
}

Constructors 

  • AllTime
  • LastDays(Int)
  • LastWeeks(Int)
  • LastMonths(Int)
  • LastYears(Int)
  • Range(start: String, end: String)

Values

artist_hash

</> 
pub fn artist_hash(album_artist: String) -> String

Identity hash of an artist.

default_endpoint

</> 
pub const default_endpoint: String

The default AppView base URL used by the no-argument read functions.

follow

</> 
pub fn follow(
  agent: dynamic.Dynamic,
  did: String,
) -> dynamic.Dynamic

Follow an account by DID.

get

</> 
pub fn get(nsid: String, params_json: String) -> dynamic.Dynamic

Call any app.rocksky.* read query by nsid. params_json is a JSON object of string params ("{\"uri\":\"at://…\"}") — the whole read-query catalog is reachable here.

get_at

</> 
pub fn get_at(
  nsid: String,
  params_json: String,
  endpoint: String,
) -> dynamic.Dynamic

get against a custom AppView endpoint.

get_authed

</> 
pub fn get_authed(
  nsid: String,
  params_json: String,
  token: String,
) -> dynamic.Dynamic

get with a bearer access token (for auth-gated queries).

global_stats

</> 
pub fn global_stats() -> dynamic.Dynamic

Platform-wide totals.

global_stats_at

</> 
pub fn global_stats_at(endpoint: String) -> dynamic.Dynamic

global_stats against a custom AppView endpoint.

hydrate_from_jetstream

</> 
pub fn hydrate_from_jetstream(
  agent: dynamic.Dynamic,
) -> dynamic.Dynamic

Keep the local dedup index hydrated from Jetstream in the background.

like

</> 
pub fn like(
  agent: dynamic.Dynamic,
  uri: String,
  cid: String,
) -> dynamic.Dynamic

Like a record by strong reference.

login

</> 
pub fn login(
  session_path: String,
  identifier: String,
  password: String,
) -> dynamic.Dynamic

Log in with an app password, persisting the session at session_path.

match_song

</> 
pub fn match_song(
  title: String,
  artist: String,
) -> dynamic.Dynamic

Resolve full canonical metadata for a bare title + artist (matchSong).

profile

</> 
pub fn profile(actor: String) -> dynamic.Dynamic

An actor’s detailed profile.

profile_at

</> 
pub fn profile_at(
  actor: String,
  endpoint: String,
) -> dynamic.Dynamic

profile against a custom AppView endpoint.

refresh_session

</> 
pub fn refresh_session(agent: dynamic.Dynamic) -> dynamic.Dynamic

Proactively refresh the session (keep-alive).

scrobble_match

</> 
pub fn scrobble_match(
  agent: dynamic.Dynamic,
  title: String,
  artist: String,
  album: String,
  mb_id: String,
  isrc: String,
) -> dynamic.Dynamic

Scrobble from just a title + artist (pass “” for no album; optional mb_id / isrc anchor the match): resolve full metadata via matchSong, then fan out.

scrobbles

</> 
pub fn scrobbles(
  actor: String,
  limit: Int,
  offset: Int,
) -> dynamic.Dynamic

An actor’s scrobbles, newest first.

scrobbles_at

</> 
pub fn scrobbles_at(
  actor: String,
  limit: Int,
  offset: Int,
  endpoint: String,
) -> dynamic.Dynamic

scrobbles against a custom AppView endpoint.

shout

</> 
pub fn shout(
  agent: dynamic.Dynamic,
  subject_uri: String,
  subject_cid: String,
  message: String,
) -> dynamic.Dynamic

Post a shout on a subject.

song_hash

</> 
pub fn song_hash(
  title: String,
  artist: String,
  album: String,
) -> String

Identity hash of a song — identical across every Rocksky SDK.

sync_repo

</> 
pub fn sync_repo(agent: dynamic.Dynamic) -> dynamic.Dynamic

Download the caller’s repo and (re)build the local dedup index. Requires the agent to have been given a dedup store.

top_artists_interval

</> 
pub fn top_artists_interval(
  limit: Int,
  offset: Int,
  interval: Interval,
) -> dynamic.Dynamic

Platform-wide top artists chart over a typed Interval.

top_artists_interval_at

</> 
pub fn top_artists_interval_at(
  limit: Int,
  offset: Int,
  interval: Interval,
  endpoint: String,
) -> dynamic.Dynamic

top_artists_interval against a custom AppView endpoint.

top_tracks

</> 
pub fn top_tracks(limit: Int, offset: Int) -> dynamic.Dynamic

Platform-wide top tracks chart.

top_tracks_at

</> 
pub fn top_tracks_at(
  limit: Int,
  offset: Int,
  endpoint: String,
) -> dynamic.Dynamic

top_tracks against a custom AppView endpoint.

top_tracks_interval

</> 
pub fn top_tracks_interval(
  limit: Int,
  offset: Int,
  interval: Interval,
) -> dynamic.Dynamic

Platform-wide top tracks chart over a typed Interval.

top_tracks_interval_at

</> 
pub fn top_tracks_interval_at(
  limit: Int,
  offset: Int,
  interval: Interval,
  endpoint: String,
) -> dynamic.Dynamic

top_tracks_interval against a custom AppView endpoint.

✨ Search Document