ProtoRune (proto_rune v0.2.0)

Copy Markdown

Main API for ProtoRune - Elixir SDK for AT Protocol.

ProtoRune provides a functional, type-safe interface for interacting with AT Protocol services, including Bluesky.

Quick Start

# Login to create a session
{:ok, session} = ProtoRune.login("alice.bsky.social", "app-password")

# Post to Bluesky
{:ok, post} = ProtoRune.post(session, "Hello from Elixir!")

# Identity resolution
{:ok, did} = ProtoRune.resolve_handle("bob.bsky.social")

Architecture

  • Core API (this module): Simple, high-level functions
  • ATProto Layer: Protocol operations (Identity, Repo, Server)
  • Bsky Layer: Bluesky-specific API
  • Bot Framework: Event-driven bot development

Summary

Types

did()
error()
handle()
session()
user_identifier()
user_password()

Functions

get_session(session)

Gets current session information.

is_did(term)

Guard to check if a value is a valid DID format.

is_handle(term)

Guard to check if a value is a valid handle format.

login(identifier, password, opts \\ [])

Authenticates with AT Protocol and creates a session.

post(session, text, opts \\ [])

Posts a text message to Bluesky.

refresh_session(session)

Refreshes an expired session using the refresh token.

resolve_did(did)

Resolves a DID to its DID document.

resolve_handle(handle)

Resolves a handle to a DID (Decentralized Identifier).

valid_did?(did)

Validates DID syntax (does not resolve or verify).

valid_handle?(handle)

Validates handle syntax (does not resolve or verify).

validate_identity(handle)

Validates that a handle correctly maps to its DID.

Types

did()

@type did() :: String.t()

error()

@type error() :: {:error, term()}

handle()

@type handle() :: String.t()

session()

@type session() :: ProtoRune.Atproto.Session.t() | map()

user_identifier()

@type user_identifier() :: String.t()

user_password()

@type user_password() :: String.t()

Functions

get_session(session)

@spec get_session(session()) :: {:ok, map()} | error()

Gets current session information.

Examples

{:ok, info} = ProtoRune.get_session(session)

is_did(term)

(macro)

Guard to check if a value is a valid DID format.

is_handle(term)

(macro)

Guard to check if a value is a valid handle format.

login(identifier, password, opts \\ [])

@spec login(user_identifier(), user_password(), keyword()) ::
  {:ok, session()} | error()

Authenticates with AT Protocol and creates a session.

Parameters

  • identifier - Handle (e.g., "alice.bsky.social") or email
  • password - App password (NOT your main account password)
  • opts - Optional keyword list:

Returns

  • {:ok, session} - Session with access tokens and DID
  • {:error, reason} - Authentication failed

Examples

{:ok, session} = ProtoRune.login("alice.bsky.social", "abcd-1234-efgh-5678")

{:ok, session} = ProtoRune.login(
  "alice.bsky.social",
  "abcd-1234-efgh-5678",
  service: "https://custom-pds.example.com"
)

post(session, text, opts \\ [])

@spec post(session(), String.t(), keyword()) :: {:ok, map()} | error()

Posts a text message to Bluesky.

Examples

{:ok, post} = ProtoRune.post(session, "Hello Bluesky!")

{:ok, post} = ProtoRune.post(session, "Hello!", langs: ["en"])

refresh_session(session)

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

Refreshes an expired session using the refresh token.

Examples

{:ok, fresh_session} = ProtoRune.refresh_session(session)

resolve_did(did)

@spec resolve_did(did()) :: {:ok, map()} | error()

Resolves a DID to its DID document.

Results are cached for 24 hours.

Examples

{:ok, doc} = ProtoRune.resolve_did("did:plc:abc123xyz")

resolve_handle(handle)

@spec resolve_handle(handle()) :: {:ok, did()} | error()

Resolves a handle to a DID (Decentralized Identifier).

Results are cached for 1 hour.

Examples

{:ok, did} = ProtoRune.resolve_handle("alice.bsky.social")
# => {:ok, "did:plc:abc123xyz"}

valid_did?(did)

@spec valid_did?(term()) :: boolean()

Validates DID syntax (does not resolve or verify).

valid_handle?(handle)

@spec valid_handle?(term()) :: boolean()

Validates handle syntax (does not resolve or verify).

validate_identity(handle)

@spec validate_identity(handle()) :: {:ok, map()} | error()

Validates that a handle correctly maps to its DID.

Examples

{:ok, doc} = ProtoRune.validate_identity("alice.bsky.social")