rocksky - v1.0.0

rocksky

Rocksky — a Gleam SDK for the Rocksky XRPC API.

The API is pipe-friendly: build a Request(a) with the relevant endpoint constructor, chain param functions on it, then hand it to send together with a Client.

import rocksky
import rocksky/actor

pub fn main() {
  let client =
    rocksky.new()
    |> rocksky.with_bearer_token("xxx")

  let assert Ok(profile) =
    actor.get_profile(did: "alice.bsky.social")
    |> rocksky.send(client)

  let assert Ok(scrobbles) =
    actor.get_actor_scrobbles(did: "alice.bsky.social")
    |> rocksky.limit(50)
    |> rocksky.offset(0)
    |> rocksky.send(client)
}

Types

Client

opaque </>

A configured Rocksky client. Build one with new() and tweak it via the with_* setters before passing it to send.

pub opaque type Client

Request

opaque </>

A configured but unsent XRPC call. a is the type of the decoded response. Build one with query or procedure (or via an endpoint module), refine it with chained param helpers, then execute it with send.

pub opaque type Request(a)

SendFn

</>

The signature of the transport function used by the client. Swap your own in via with_send to test offline or to target a different runtime (e.g. JavaScript via a fetch-backed function).

pub type SendFn =
  fn(request.Request(String)) -> Result(
    response.Response(String),
    String,
  )

Values

base_url

</> 
pub fn base_url(client: Client) -> String

Expose the configured base URL (e.g. for logging or sharing config).

body

</> 
pub fn body(req: Request(a), body: json.Json) -> Request(a)

Attach a JSON body to a request. Procedures often need this.

bool_param

</> 
pub fn bool_param(
  req: Request(a),
  name: String,
  value: Bool,
) -> Request(a)

Add a single boolean query parameter (true / false).

cursor

</> 
pub fn cursor(req: Request(a), c: String) -> Request(a)

default_base_url

</> 
pub const default_base_url: String

The public Rocksky API endpoint.

default_user_agent

</> 
pub const default_user_agent: String

The default User-Agent header value sent by the SDK.

end_date

</> 
pub fn end_date(req: Request(a), date: String) -> Request(a)

genre

</> 
pub fn genre(req: Request(a), g: String) -> Request(a)
</> 
pub fn header(
  req: Request(a),
  name: String,
  value: String,
) -> Request(a)

Attach a header to just this request (in addition to any defaults the client sets).

int_param

</> 
pub fn int_param(
  req: Request(a),
  name: String,
  value: Int,
) -> Request(a)

Add a single integer query parameter (stringified at send time).

limit

</> 
pub fn limit(req: Request(a), n: Int) -> Request(a)

new

</> 
pub fn new() -> Client

Build a fresh client targeting default_base_url with no authentication.

offset

</> 
pub fn offset(req: Request(a), n: Int) -> Request(a)

param

</> 
pub fn param(
  req: Request(a),
  name: String,
  value: String,
) -> Request(a)

Add a single string query parameter.

procedure

</> 
pub fn procedure(
  nsid: String,
  decoder: decode.Decoder(a),
) -> Request(a)

Start building a procedure (HTTP POST). See query for usage notes.

query

</> 
pub fn query(
  nsid: String,
  decoder: decode.Decoder(a),
) -> Request(a)

Start building a query (HTTP GET) against /xrpc/{nsid}. Endpoint modules call this; you only need it directly to reach an XRPC method the SDK hasn’t surfaced yet.

repeated_param

</> 
pub fn repeated_param(
  req: Request(a),
  name: String,
  values: List(String),
) -> Request(a)

Add a query parameter repeated once per value (XRPC convention for array-typed parameters, e.g. getFollowers?dids=did:plc:a&dids=did:plc:b).

send

</> 
pub fn send(
  req: Request(a),
  client: Client,
) -> Result(a, error.RocksyError)

Send a request through the client and decode the response.

size

</> 
pub fn size(req: Request(a), n: Int) -> Request(a)

start_date

</> 
pub fn start_date(req: Request(a), date: String) -> Request(a)

with_base_url

</> 
pub fn with_base_url(client: Client, url: String) -> Client

Point the client at a different deployment. Trailing slashes are trimmed.

with_bearer_token

</> 
pub fn with_bearer_token(client: Client, token: String) -> Client

Attach a Bluesky session token (sent as Authorization: Bearer <token>).

with_header

</> 
pub fn with_header(
  client: Client,
  name: String,
  value: String,
) -> Client

Add a header that ships with every request from this client. To attach a header to a single request, use header on the request value.

with_send

</> 
pub fn with_send(
  client: Client,
  send: fn(request.Request(String)) -> Result(
    response.Response(String),
    String,
  ),
) -> Client

Replace the transport function. Mostly useful for tests and for JS targets where you want to plug in a custom fetch.

with_user_agent

</> 
pub fn with_user_agent(
  client: Client,
  user_agent: String,
) -> Client

Override the User-Agent header. Identify your app, please.

without_token

</> 
pub fn without_token(client: Client) -> Client

Remove any previously-set bearer token.

year

</> 
pub fn year(req: Request(a), y: Int) -> Request(a)
✨ Search Document