+14 -9

src/possum.gleam

Reviewed

··· 8 8 //// general account management interfaces such as the OAuth login screen. 9 9 //// PDSes actively sync their data repos with Relays. 10 10 //// 11 11 + //// ## Lexicon 12 12 + //// 13 13 + //// Lexicon is a schema language. It's used in the Atmosphere to describe data 14 14 + //// records and HTTP APIs. It's very similar to JSON-Schema and OpenAPI. 15 15 + //// Lexicon's sole purpose is to help developers build compatible software. 16 16 + //// 11 17 //// ## Record Keys 12 18 //// 13 19 //// A record key (sometimes shortened to "rkey") is used to name and reference an individual ··· 45 51 /// Documentation: [xrpc/com.atproto.sync](https://endpoints.bsky.app/#bluesky-app/tag/comatprotosync) 46 52 const com_atproto_sync = "xrpc/com.atproto.sync" 47 53 48 48 - /// Get current PLC Data for the indicated DID, 54 54 + /// Get current [PLC](https://web.plc.directory/) Data for the indicated DID, 49 55 /// this returns information about a Decentralized Identifier (DID), 50 50 - /// including their handle and service endpoint. 56 56 + /// including their **handle** and **PDS endpoint**. 51 57 /// 52 58 /// PLC is a persistent global identifier system, stands for 53 59 /// "Public Ledger of Credentials". ··· 55 61 /// ## Examples 56 62 /// 57 63 /// ```gleam 58 58 - /// import gleam/http/request 59 64 /// import possum/did 60 65 /// import possum 61 66 /// ··· 63 68 /// let request = possum.get_plc_data(did) 64 69 /// 65 70 /// // You can use this decoder to extract the server endpoint 66 66 - /// let decoder = decode.at(["services", "atproto_pds", "endpoint"], decode.string) 71 71 + /// let decoder = 72 72 + /// decode.at( 73 73 + /// ["services", "atproto_pds", "endpoint"], 74 74 + /// decode.string 75 75 + /// ) 67 76 /// ``` 68 77 /// 69 78 /// ## Response ··· 88 97 /// } 89 98 /// } 90 99 /// ``` 91 91 - /// 92 92 - /// Documentation: [DID PLC Directory](https://web.plc.directory/) 93 93 - /// 94 94 - /// See also: [did](possum/did.html), [did.parse](possum/did.html#parse) 95 100 pub fn get_plc_data(did: did.Did) -> request.Request(String) { 96 101 request.Request( 97 102 method: http.Get, ··· 162 167 /// 163 168 /// Endpoint Docs: [/xrpc/com.atproto.identity.resolveHandle](https://endpoints.bsky.app/#bluesky-app/tag/comatprotoidentity/GET/xrpc/com.atproto.identity.resolveHandle) 164 169 /// 165 165 - /// See also: [did](possum/did.html), [did.parse](possum/did.html#parse) 170 170 + /// See also: [Did](possum/did.html#Did), [handle.parse](possum/handle.html#parse) 166 171 pub fn resolve_handle( 167 172 handle: handle.Handle, 168 173 pds host: String,

+12 -10

src/possum/at_uri.gleam

Reviewed

··· 1 1 - //// The AT URI scheme (at://) makes it easy to reference individual records in 2 2 - //// a specific repository, identified by either DID or handle. 3 3 - //// 4 4 - //// AT URIs are not content-addressed, so the contents of the record they 5 5 - //// refer to may also change over time. 6 6 - //// 7 7 - //// Documentation: [AT URI Scheme](https://atproto.com/specs/at-uri-scheme) 8 8 - 9 1 import gleam/result 10 2 import gleam/string 11 3 import possum/did ··· 39 31 Did(value: did.Did) 40 32 } 41 33 42 42 - /// A URI scheme for addressing atproto repository data. 34 34 + /// The AT URI scheme (at://) makes it easy to reference individual records in 35 35 + /// a specific repository, identified by either DID or handle. 43 36 /// 44 44 - /// See also: [parse](#parse) 37 37 + /// ``` 38 38 + /// at://did:plc:vwzwgnygau7ed7b7wt5ux7y2/app.bsky.feed.post/3k5nobkf2w72g 39 39 + /// └──────────────────────────────┘ └────────────────┘ └───────────┘ 40 40 + /// authority colection rkey 41 41 + /// ``` 42 42 + /// 43 43 + /// AT URIs are not content-addressed, so the contents of the record they 44 44 + /// refer to may also change over time. 45 45 + /// 46 46 + /// Documentation: [AT URI Scheme](https://atproto.com/specs/at-uri-scheme) 45 47 pub opaque type AtUri { 46 48 AtUri( 47 49 /// Identifier, can be a DID or a Handle

+10 -28

src/possum/did.gleam

Reviewed

··· 1 1 - //// ## DID (Decentralized ID) 2 2 - //// 3 3 - //// DIDs, or Decentralized IDentifiers, are universally-unique identifiers which 4 4 - //// represent data repos. They are permanent and non-human-readable. 5 5 - //// DIDs are a W3C specification. The AT Protocol currently supports 6 6 - //// did:web and did:plc, two different DID methods. 7 7 - //// 8 8 - //// DIDs resolve to documents which contain metadata about a repo, 9 9 - //// including the address of the repo's PDS, the repo's handles, 10 10 - //// and the public signing keys. 11 11 - 12 1 import gleam/dynamic/decode 13 2 import gleam/regexp 14 3 import gleam/result ··· 26 15 InvalidDidMethod(value: String) 27 16 } 28 17 29 29 - /// AT Protocol uses Decentralized Identifiers (DIDs) as persistent account 30 30 - /// identifiers. An example DID is `did:plc:ewvi7nxzyoun6zhxrhs64oiz`. 18 18 + /// AT Protocol uses Decentralized Identifiers (DIDs) universally-unique 19 19 + /// identifiers which represent data repos. For example: 20 20 + /// 21 21 + /// ``` 22 22 + /// did:plc:k5vecqzf4d5mdvkcu3mx6l5g 23 23 + /// └─┘ └──────────────────────┘ 24 24 + /// method identifier 25 25 + /// ``` 31 26 /// 32 27 /// Documentation: [Decentralized Identifiers](https://atproto.com/specs/did) 33 28 /// ··· 48 43 /// 49 44 /// assert method == did.Plc 50 45 /// ``` 51 51 - /// 52 52 - /// See also: [Did](#Did) 53 46 pub fn method(self: Did) -> Method { 54 47 self.method 55 48 } ··· 57 50 /// Return the DID identifier. 58 51 /// 59 52 /// This function **does not** convert the value into a valid DID format, 60 60 - /// for that use `to_string`. 53 53 + /// for that use [to_string](#to_string). 61 54 /// 62 55 /// ## Examples 63 56 /// ··· 69 62 /// 70 63 /// assert identifier == "k5vecqzf4d5mdvkcu3mx6l5g" 71 64 /// ``` 72 72 - /// 73 73 - /// See also: [Did](#Did) 74 65 pub fn indentifer(self: Did) -> String { 75 66 self.identifier 76 67 } ··· 112 103 /// Documentation: [Blessed DID Methods](https://atproto.com/specs/did#blessed-did-methods) 113 104 pub type Method { 114 105 /// Self-authenticating DID method developed specifically for use with atproto. 115 115 - /// See the DID PLC [website](https://web.plc.directory/) for more details. 116 106 Plc 117 107 /// [W3C community](https://w3c-ccg.github.io/did-method-web/) draft based 118 118 - /// on HTTPS (and DNS). The identifier section is a hostname. 119 119 - /// This method is supported in atproto to provide an independent 120 120 - /// alternative to `did:plc`. 121 121 - /// 122 122 - /// The special localhost hostname is allowed, but only in testing and development 123 123 - /// environments. Port numbers (with separating colon hex-encoded) are only 124 124 - /// allowed for localhost, and only in testing and development. 125 125 - /// 126 126 - /// Documentation: [did:web](https://atproto.com/specs/did#did-web-in-at-protocol) 108 108 + /// on HTTPS (and DNS). The identifier section is a _hostname_. 127 109 Web 128 110 } 129 111

+13 -17

src/possum/nsid.gleam

Reviewed

··· 1 1 - //// Namespaced Identifiers (NSIDs) are used to reference Lexicon schemas for 2 2 - //// records, XRPC endpoints, and more. For example, `com.atproto.sync.getRecord`. 3 3 - //// 4 4 - //// The basic structure and semantics of an NSID are a fully-qualified hostname 5 5 - //// in reverse domain-name order, followed by an additional name segment. 6 6 - //// The hostname part is the **domain authority**, and the final segment is the **name**. 7 7 - //// 8 8 - //// ## Lexicon 9 9 - //// 10 10 - //// Lexicon is a schema language. It's used in the Atmosphere to describe data 11 11 - //// records and HTTP APIs. Functionally it's very similar to JSON-Schema and OpenAPI. 12 12 - //// Lexicon's sole purpose is to help developers build compatible software. 13 13 - //// 14 14 - //// Documentation: [Namespaced Identifiers](https://atproto.com/specs/nsid) 15 15 - 16 1 import gleam/regexp 17 2 import gleam/result 18 3 ··· 26 11 InvalidSyntax(value: String) 27 12 } 28 13 29 29 - /// A specification for global semantic IDs. 14 14 + /// Namespaced Identifiers (NSIDs) are used to reference Lexicon schemas for 15 15 + /// records, endpoints, and more. For example: 16 16 + /// 17 17 + /// ``` 18 18 + /// sh.tangled.repo.pull 19 19 + /// └─────────────┘ └──┘ 20 20 + /// authority name 21 21 + /// ```` 22 22 + /// 23 23 + /// The basic structure of an NSID are a hostname in reverse domain-name order, 24 24 + /// followed by an additional name segment. The hostname part is called the 25 25 + /// **domain authority**, and the final segment is the **name**. 30 26 /// 31 31 - /// See also: [parse](#parse) 27 27 + /// Documentation: [Namespaced Identifiers](https://atproto.com/specs/nsid) 32 28 pub opaque type Nsid { 33 29 Nsid(value: String) 34 30 }