# Possum 🐀

ATproto library for gleam. Helps you build HTTP requests that interact with
your [Personal Data Server](https://docs.bsky.app/docs/advanced-guides/atproto#achieving-scale).

## 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

```sh
gleam add possum gleam_http 
```

### Consulting your DID

```gleam
// Resolve an atproto handle (hostname) to a DID.
//
// 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.
request.new()
|> request.set_host("slingshot.microcosm.blue")
|> possum.resolve_handle("gleam.run")

// You also verify your DID without DNS by sending a request to `/.well-know/atproto-did`
// Your server can then respond with the DID value as plain text.
request.new()
|> possum.resolve_well_known_did("gleam.run")

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

### Querying Public Data

```gleam
// Reading public data from repositories.
// No authorization needed.
request.new()
|> request.set_host("personal.data-server.pds")
|> possum.list_records(
  did: did,
  collection: "site.standard.document",
  limit: option.Some(3),
  cursor: option.None,
  reverse: option.None,
)
```

### Authorized Requests

```gleam
// Include a authorization Header for requests that require authentication.
request.new()
|> request.set_host("personal.data-server.pds")
|> possum.authorized("my-access-token")

// Refreshing an authorized Session
request.new()
|> request.set_host("personal.data-server.pds")
|> possum.refresh_session("refresh-token")
```