Atex.XRPC (atex v0.6.0)

XRPC client module for AT Protocol RPC calls.

This module provides both authenticated and unauthenticated access to AT Protocol XRPC endpoints. The authenticated functions (get/3, post/3) work with any client that implements the Atex.XRPC.Client.

Example usage

# Login-based client
{:ok, client} = Atex.XRPC.LoginClient.login("https://bsky.social", "user.bsky.social", "password")
{:ok, response, client} = Atex.XRPC.get(client, "app.bsky.actor.getProfile", params: [actor: "user.bsky.social"])

# OAuth-based client
{:ok, oauth_client} = Atex.XRPC.OAuthClient.from_conn(conn)
{:ok, response, oauth_client} = Atex.XRPC.get(oauth_client, "app.bsky.actor.getProfile", params: [actor: "user.bsky.social"])

Unauthenticated requests

Unauthenticated functions (unauthed_get/3, unauthed_post/3) do not require a client and work directly with endpoints:

{:ok, response} = Atex.XRPC.unauthed_get("https://bsky.social", "com.atproto.sync.getHead", params: [did: "did:plc:..."])

Summary

Functions

get(client, name, opts \\ [])

Perform a HTTP GET on a XRPC resource. Called a "query" in lexicons.

post(client, name, opts \\ [])

Perform a HTTP POST on a XRPC resource. Called a "procedure" in lexicons.

unauthed_get(endpoint, name, opts \\ [])

Like get/3 but is unauthenticated by default.

unauthed_post(endpoint, name, opts \\ [])

Like post/3 but is unauthenticated by default.

url(endpoint, resource)

Create an XRPC url based on an endpoint and a resource name.

Functions

get(client, name, opts \\ [])

@spec get(Atex.XRPC.Client.client(), String.t() | struct(), keyword()) ::
  {:ok, Req.Response.t(), Atex.XRPC.Client.client()}
  | {:error, any(), Atex.XRPC.Client.client()}

Perform a HTTP GET on a XRPC resource. Called a "query" in lexicons.

Accepts any client that implements Atex.XRPC.Client and returns both the response and the (potentially updated) client.

Can be called either with the XRPC operation name as a string, or with a lexicon struct (generated via deflexicon) for type safety and automatic parameter/response handling.

When using a lexicon struct, the response body will be automatically converted to the corresponding type if an Output struct exists for the lexicon.

Examples

# Using string XRPC name
{:ok, response, client} =
  Atex.XRPC.get(client, "app.bsky.actor.getProfile", params: [actor: "ovyerus.com"])

# Using lexicon struct with typed construction
{:ok, response, client} =
  Atex.XRPC.get(client, %App.Bsky.Actor.GetProfile{
    params: %App.Bsky.Actor.GetProfile.Params{actor: "ovyerus.com"}
  })

post(client, name, opts \\ [])

@spec post(Atex.XRPC.Client.client(), String.t() | struct(), keyword()) ::
  {:ok, Req.Response.t(), Atex.XRPC.Client.client()}
  | {:error, any(), Atex.XRPC.Client.client()}

Perform a HTTP POST on a XRPC resource. Called a "procedure" in lexicons.

Accepts any client that implements Atex.XRPC.Client and returns both the response and the (potentially updated) client.

Can be called either with the XRPC operation name as a string, or with a lexicon struct (generated via deflexicon) for type safety and automatic input/parameter mapping.

When using a lexicon struct, the response body will be automatically converted to the corresponding type if an Output struct exists for the lexicon.

Examples

# Using string XRPC name
{:ok, response, client} =
  Atex.XRPC.post(
    client,
    "com.atproto.repo.createRecord",
    json: %{
      repo: "did:plc:...",
      collection: "app.bsky.feed.post",
      rkey: Atex.TID.now() |> to_string(),
      record: %{
        text: "Hello World",
        createdAt: NaiveDateTime.to_iso8601(NaiveDateTime.utc_now())
      }
    }
  )

# Using lexicon struct with typed construction
{:ok, response, client} =
  Atex.XRPC.post(client, %Com.Atproto.Repo.CreateRecord{
    input: %Com.Atproto.Repo.CreateRecord.Input{
      repo: "did:plc:...",
      collection: "app.bsky.feed.post",
      rkey: Atex.TID.now() |> to_string(),
      record: %App.Bsky.Feed.Post{
        text: "Hello World!",
        createdAt: NaiveDateTime.to_iso8601(NaiveDateTime.utc_now())
      }
    }
  })

unauthed_get(endpoint, name, opts \\ [])

@spec unauthed_get(String.t(), String.t(), keyword()) ::
  {:ok, Req.Response.t()} | {:error, any()}

Like get/3 but is unauthenticated by default.

unauthed_post(endpoint, name, opts \\ [])

@spec unauthed_post(String.t(), String.t(), keyword()) ::
  {:ok, Req.Response.t()} | {:error, any()}

Like post/3 but is unauthenticated by default.

url(endpoint, resource)

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

Create an XRPC url based on an endpoint and a resource name.

Example

iex> Atex.XRPC.url("https://bsky.app", "app.bsky.actor.getProfile")
"https://bsky.app/xrpc/app.bsky.actor.getProfile"