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)
```

ScrobbleMatch

</>

Input for scrobble_match: title + artist required, the rest optional (album override, mb_id / isrc match anchors, scrobbled-at Unix seconds).

pub type ScrobbleMatch {
  ScrobbleMatch(
    title: String,
    artist: String,
    album: option.Option(String),
    mb_id: option.Option(String),
    isrc: option.Option(String),
    timestamp: option.Option(Int),
  )
}

Constructors

ScrobbleMatch(
  title: String,
  artist: String,
  album: option.Option(String),
  mb_id: option.Option(String),
  isrc: option.Option(String),
  timestamp: option.Option(Int),
)

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.

</>

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

match_song

</>

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

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

notifications

</>

pub fn notifications(
  token: String,
  params_json: String,
) -> dynamic.Dynamic

The authenticated viewer’s notifications, most recent first. params_json is a JSON object that may contain "limit" (default 30) and "cursor".

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).

reply_shout_with_gif

</>

pub fn reply_shout_with_gif(
  agent: dynamic.Dynamic,
  subject_uri: String,
  subject_cid: String,
  parent_uri: String,
  parent_cid: String,
  message: String,
  gif_json: String,
) -> dynamic.Dynamic

Reply to a shout with an optional GIF/sticker/clip (see shout_with_gif), plus a parent strong-ref.

scrobble_match

</>

pub fn scrobble_match(
  agent: dynamic.Dynamic,
  input: ScrobbleMatch,
) -> dynamic.Dynamic

Scrobble from a title + artist: resolve full metadata via matchSong, then fan out. Unset optionals (None) are ignored.

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.

shout_with_gif

</>

pub fn shout_with_gif(
  agent: dynamic.Dynamic,
  subject_uri: String,
  subject_cid: String,
  message: String,
  gif_json: String,
) -> dynamic.Dynamic

Post a shout with an optional GIF/sticker/clip. Pass at least one of message / gif_json (a JSON gif embed with "url" required, plus "previewUrl", "alt", "width", "height"; "" for none).

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.

unread_count

</>

pub fn unread_count(token: String) -> dynamic.Dynamic

The authenticated viewer’s unread-notification count. Returns {"count": n}.

update_seen

</>

pub fn update_seen(
  token: String,
  ids_json: String,
) -> dynamic.Dynamic

Mark notifications as viewed. ids_json is a JSON array of notification ids ("[\"id1\",\"id2\"]"), or "[]" to mark all. Returns {"unreadCount": n}.