Rust

rocksky-sdk is the Rust SDK and the shared engine behind every other Rocksky SDK. Built on jacquard, it mirrors Bluesky’s @atproto/api: RockskyAgent wraps a session and exposes high-level write verbs; reads go through the unauthenticated AppView. It also ships an optional dedup index and Jetstream real-time sync.

Install

[dependencies]
rocksky-sdk = { version = "0.4", features = ["dedup", "jetstream"] }

The dedup and jetstream features are optional (they pull in RocksDB + the firehose client).

Quickstart

use rocksky_sdk::{RockskyAgent, ScrobbleDraft};

let agent = RockskyAgent::builder()
    .session_store("~/.config/rocksky/session.json")
    .build()?;
agent.login_password("alice.bsky.social", "app-password").await?;

// Reads — via the bundled AppView client.
let recent = agent.appview().scrobbles("alice.bsky.social", 25, 0).await?;

// Writes — the scrobble fans out to artist/album/song then the scrobble.
agent.scrobble(&ScrobbleDraft {
    title: "Chaser".into(), artist: "Calibro 35".into(),
    album: "Jazzploitation".into(), album_artist: "Calibro 35".into(),
    duration_ms: 182_320, ..Default::default()
}).await?;

API

Reads — AppView: the full app.rocksky.* read surface. Basics: profile, scrobbles, songs, albums, artists, feed, search, top_artists, top_tracks, global_stats. Catalog & relations: catalog_albums, catalog_artists, catalog_songs, album_tracks, artist_albums, artist_tracks, loved_songs, scrobble_feed, scrobble (single by uri), follows, followers, known_followers. Raw-JSON detail/long-tail methods: album, artist, song, playlists, playlist, stats, wrapped, scrobbles_chart, recommendations, neighbours, shouts, and more. get(nsid, &params) is the universal escape hatch — calls any read query by nsid and returns raw serde_json::Value; every named method is sugar over it. match_song(title, artist, mb_id, isrc) resolves a bare title + artist into full canonical metadata. Attach a bearer token for auth-gated queries with AppView::new(base).with_token(token) (or set_token). Date-window charts: top_tracks_interval / top_artists_interval take a typed DateInterval — AllTime, LastDays(n), LastWeeks(n), LastMonths(n), LastYears(n), or Range { start, end }; top_tracks / top_artists remain all-time shorthands.

use rocksky_sdk::DateInterval;

let month = av.top_tracks_interval(DateInterval::LastDays(30), 50, 0).await?;

Writes — RockskyAgent: scrobble (fan-out from full metadata), scrobble_match(&ScrobbleMatch { .. }) (resolves metadata via match_song, then the same fan-out; title/artist required, album/mb_id/isrc/timestamp optional), create_song / create_album / create_artist, like / unlike, follow / unfollow, shout / reply_shout, set_now_playing / clear_now_playing. App-password + loopback OAuth login. Identity hashes: rocksky_sdk::dedup::{song_hash, album_hash, artist_hash}.

Duplicate prevention & real-time sync

With the dedup feature, attach a RocksDB-backed index; with jetstream, keep it live off the firehose:

let agent = RockskyAgent::builder()
    .session_store("session.json")
    .dedup_store("dedup")        // requires the `dedup` feature
    .build()?;

agent.sync_repo().await?;                 // backfill from the repo CAR
tokio::spawn(async move { agent.hydrate_from_jetstream().await });

Overview

Language SDKs

Install

Quickstart

API

Duplicate prevention & real-time sync

​Install

​Quickstart

​API

​Duplicate prevention & real-time sync

Install

Quickstart

API

Duplicate prevention & real-time sync