Possum 🐀#

ATproto library for gleam. Helps you build HTTP requests that interact with your Personal Data Server. The user is responsible for sending the request and decoding the response.

AT Protocol#

The AT Protocol stands for "Authenticated Transfer Protocol", the name is in reference to the fact that all user-data is signed by the authoring users, which makes it possible to broadcast the data through many services and prove it's real without having to speak directly to the originating server.

Example#

gleam add possum gleam_http gleam_json

Decentralized Identifiers (DIDs)#

import possum/did
import possum/handle
import possum

// You can consult your identifier by sending a request directly to your PDS,
// or you can use projects like [Slingshot](https://slingshot.microcosm.blue)
// for easy access to cached data when resolving a handle.

// Handle validation
let assert Ok(handle) = handle.parse("gleam.run")

// Resolve an atproto handle (hostname) to a DID.
let request =
  possum.resolve_handle(handle, pds: "slingshot.microcosm.blue")

// Use `did.parse` to turn strings into valid DID format
let assert Ok(did) = did.parse("did:plc:ewvi7nxzyoun6zhxrhs64oiz")

Building HTTP Requests#

import possum/did
import possum/nsid
import possum

let assert Ok(did) = did.parse("did:plc:ewvi7nxzyoun6zhxrhs64oiz")
let assert Ok(collection) = nsid.parse("site.standard.document")

// Reading public data from repositories, no Authorization needed.
let request =
  possum.list_records(
    did,
    pds: "personal.data-server.pds",
    collection:,
    limit: option.Some(3),
    cursor: option.None,
    reverse: option.None,
  )

Authorized Requests#

import gleam/http/request
import possum/did
import possum

let assert Ok(did) = did.parse("did:plc:ewvi7nxzyoun6zhxrhs64oiz")

// App Passwords can be generated in your Bluesky settings,
// It allows authorized access to your PDS.
let requests =
  possum.create_session(
    did,
    pds: "personal.data-server.pds",
    app_password: "bsky-app-password",
    allow_takendown: option.None,
    auth_factor_token: option.None
  )

// Include header for authorized requests.
request.new()
|> possum.authorized("access-token")

// Refreshing an authorized Session.
let request =
  possum.refresh_session("refresh-token", pds: "personal.data-server.pds")

Configure Feed