🐀 ATproto library for gleam
atproto
library
gleam
possum: describe what is the atmosphere
kacaii.dev
(Jun 29, 2026, 3:12 PM -0300)
9bd248a4
865618de
+56
-10
+12
README.md
+12
README.md
···
5
5
Helps you build HTTP requests that interact with your [Personal Data Server](https://docs.bsky.app/docs/advanced-guides/atproto#achieving-scale).
6
6
The user is responsible for sending the request and decode the response.
7
7
8
+
## AT Protocol
9
+
10
+
The "Atmosphere" is the term used to describe the ecosystem around the AT Protocol.
11
+
12
+
The AT Protocol stands for "Authenticated Transfer Protocol," and is frequently
13
+
shortened to "atproto." The name is in reference to the fact that all user-data
14
+
is signed by the authoring users, which makes it possible to broadcast the data
15
+
through many services and prove it's real without having to speak directly to
16
+
the originating server.
17
+
18
+
source: <https://atproto.com/guides/glossary>
19
+
8
20
## Example
9
21
10
22
```sh
+44
-10
src/possum.gleam
+44
-10
src/possum.gleam
···
1
-
//// AT Protocol uses Decentralized Identifiers (DIDs) as persistent account
2
-
//// identifiers. PLC stands for "Public Ledger of Credentials".
1
+
//// ## PDS (Personal Data Server)
3
2
////
4
-
//// DIDs are the long-term persistent identifiers for accounts in atproto,
5
-
//// but they can be opaque and unfriendly for human use.
6
-
//// Handles are mutable and human-friendly account usernames,
7
-
//// in the form of a DNS hostname. For example, user.example.com.
8
-
//// Handles must be bi-directionally linked to a DID: the DID document must claim
9
-
//// the handle, and the handle must resolve to the DID identifier.
3
+
//// A PDS, or Personal Data Server, is a server that hosts a user.
4
+
//// A PDS will always store the user's data repo and signing keys.
5
+
//// It may also assign the user a handle and a DID.
6
+
//// Many PDSes will host multiple users.
10
7
////
11
-
//// Two methods of resolving handles to DID are supported: one using
12
-
//// TXT DNS records, and the other using an HTTPS /.well-known/ URL path.
8
+
//// A PDS communicates with AppViews to run applications.
9
+
//// A PDS doesn't typically run any applications itself,
10
+
//// though it will have general account management interfaces
11
+
//// such as the OAuth login screen.
12
+
//// PDSes actively sync their data repos with Relays.
13
+
////
14
+
//// ## Lexicon
15
+
////
16
+
//// Lexicon is a schema language. It's used in the Atmosphere to describe data
17
+
//// records and HTTP APIs. Functionally it's very similar to JSON-Schema and OpenAPI.
18
+
//// Lexicon's sole purpose is to help developers build compatible software.
19
+
////
20
+
//// ## DID (Decentralized ID)
21
+
////
22
+
//// DIDs, or Decentralized IDentifiers, are universally-unique identifiers which
23
+
//// represent data repos. They are permanent and non-human-readable.
24
+
//// DIDs are a W3C specification. The AT Protocol currently supports
25
+
//// did:web and did:plc, two different DID methods.
26
+
////
27
+
//// DIDs resolve to documents which contain metadata about a repo,
28
+
//// including the address of the repo's PDS, the repo's handles,
29
+
//// and the public signing keys.
30
+
////
31
+
//// ## Record Keys
32
+
////
33
+
//// A record key (sometimes shortened to "rkey") is used to name and reference an individual
34
+
//// record within the same collection of an atproto repository.
35
+
//// It ends up as a segment in AT URIs, and in the repo MST path.
36
+
////
37
+
//// ## CID (Content ID)
38
+
////
39
+
//// CIDs, or Content Identifiers, are cryptographic hashes of records.
40
+
//// They are used to track specific versions of records.
13
41
14
42
import gleam/bool
15
43
import gleam/http
···
69
97
///
70
98
/// request.new()
71
99
/// |> possum.resolve_well_known_did("gleam.run")
100
+
///
101
+
/// assert response.body == "did=did:plc:k5vecqzf4d5mdvkcu3mx6l5g"
72
102
/// ```
73
103
///
74
104
/// Documentation: [HTTPS well-known Method](https://atproto.com/specs/handle#https-well-known-method)
···
262
292
///
263
293
/// A **record key** (rkey) is used to name and reference an individual record
264
294
/// withing the same collection of an repository.
295
+
///
296
+
/// CIDs include a metadata code which indicates whether it links to a node
297
+
/// or arbitrary binary data. In atproto, object nodes often include a string
298
+
/// field `$type` that specifies their Lexicon schema.
265
299
///
266
300
/// ```gleam
267
301
/// import gleam/http/request