Exosphere.ATProto.XRPC.Client (Exosphere v0.3.0)

XRPC HTTP client for Exosphere.ATProto.

XRPC is the HTTP API layer for Exosphere.ATProto. It provides:

Queries (GET requests) for reading data
Procedures (POST requests) for mutations

Examples

# Create a client for a PDS
client = Exosphere.ATProto.XRPC.Client.new("https://bsky.social")

# Make an unauthenticated query
{:ok, response} = Exosphere.ATProto.XRPC.Client.query(client, "com.atproto.identity.resolveHandle",
  handle: "atproto.com"
)

# Make an authenticated procedure
client = Exosphere.ATProto.XRPC.Client.new("https://bsky.social", access_token: "...")
{:ok, response} = Exosphere.ATProto.XRPC.Client.procedure(client, "com.atproto.repo.createRecord",
  repo: "did:plc:...",
  collection: "app.bsky.feed.post",
  record: %{text: "Hello!"}
)

Summary

Types

error()

procedure_body()

query_params()

t()

Functions

create_session(client, identifier, password)

Create a session (login).

describe_repo(client, repo)

Describe a repository.

get_record(client, params)

Get a record from a repository.

list_records(client, params)

List records from a repository.

new(base_url, opts \\ [])

Create a new XRPC client.

procedure(client, nsid, body \\ %{}, params \\ [])

Make an XRPC procedure (HTTP POST).

query(client, nsid, params \\ [])

Make an XRPC query (HTTP GET).

refresh_session(client)

Refresh a session using the refresh token.

upload_blob(client, data, content_type)

Upload a blob to the PDS.

with_token(client, token)

Set the access token on a client.

Types

error()

@type error() :: Exosphere.ATProto.XRPC.Error.t() | term()

procedure_body()

@type procedure_body() :: map()

query_params()

@type query_params() :: keyword() | map()

t()

@type t() :: %Exosphere.ATProto.XRPC.Client{
  access_token: String.t() | nil,
  base_url: String.t(),
  http: module() | nil,
  refresh_token: String.t() | nil,
  timeout: pos_integer() | nil
}

Functions

create_session(client, identifier, password)

@spec create_session(t(), String.t(), String.t()) :: {:ok, map()} | {:error, error()}

Create a session (login).

Examples

{:ok, session} = Exosphere.ATProto.XRPC.Client.create_session(client, "user@example.com", "password")
client = Exosphere.ATProto.XRPC.Client.with_token(client, session["accessJwt"])

describe_repo(client, repo)

@spec describe_repo(t(), String.t()) :: {:ok, map()} | {:error, error()}

Describe a repository.

Examples

{:ok, info} = Exosphere.ATProto.XRPC.Client.describe_repo(client, "did:plc:...")

get_record(client, params)

@spec get_record(
  t(),
  keyword()
) :: {:ok, map()} | {:error, error()}

Get a record from a repository.

Examples

{:ok, record} = Exosphere.ATProto.XRPC.Client.get_record(client,
  repo: "did:plc:...",
  collection: "app.bsky.feed.post",
  rkey: "3jui7kd2lry2e"
)

list_records(client, params)

@spec list_records(
  t(),
  keyword()
) :: {:ok, map()} | {:error, error()}

List records from a repository.

Examples

{:ok, %{"records" => records}} = Exosphere.ATProto.XRPC.Client.list_records(client,
  repo: "did:plc:...",
  collection: "app.bsky.feed.post",
  limit: 50
)

new(base_url, opts \\ [])

@spec new(
  String.t(),
  keyword()
) :: t()

Create a new XRPC client.

Options

:access_token - JWT access token for authentication
:refresh_token - JWT refresh token
:timeout - Request timeout in milliseconds (default: 30_000)

Examples

# Unauthenticated client
client = Exosphere.ATProto.XRPC.Client.new("https://bsky.social")

# Authenticated client
client = Exosphere.ATProto.XRPC.Client.new("https://bsky.social",
  access_token: "eyJ...",
  refresh_token: "eyJ..."
)

procedure(client, nsid, body \\ %{}, params \\ [])

@spec procedure(t(), String.t(), procedure_body() | keyword(), query_params()) ::
  {:ok, Exosphere.ATProto.HTTP.json_term()} | {:error, error()}

Make an XRPC procedure (HTTP POST).

Procedures are for mutations and may not be idempotent.

Examples

{:ok, %{"uri" => "at://...", "cid" => "bafyrei..."}} =
  Exosphere.ATProto.XRPC.Client.procedure(client, "com.atproto.repo.createRecord",
    repo: "did:plc:...",
    collection: "app.bsky.feed.post",
    record: %{"$type" => "app.bsky.feed.post", "text" => "Hello!"}
  )

query(client, nsid, params \\ [])

@spec query(t(), String.t(), query_params()) ::
  {:ok, Exosphere.ATProto.HTTP.json_term()} | {:error, error()}

Make an XRPC query (HTTP GET).

Queries are for reading data and are idempotent.

Examples

{:ok, %{"did" => "did:plc:..."}} =
  Exosphere.ATProto.XRPC.Client.query(client, "com.atproto.identity.resolveHandle",
    handle: "atproto.com"
  )

refresh_session(client)

@spec refresh_session(t()) :: {:ok, map()} | {:error, error()}

Refresh a session using the refresh token.

Returns {:error, :no_refresh_token} when the client has no refresh token.

upload_blob(client, data, content_type)

@spec upload_blob(t(), binary(), String.t()) :: {:ok, map()} | {:error, error()}

Upload a blob to the PDS.

Examples

{:ok, %{"blob" => blob}} =
  Exosphere.ATProto.XRPC.Client.upload_blob(client, image_bytes, "image/jpeg")

with_token(client, token)

@spec with_token(t(), String.t()) :: t()

Set the access token on a client.