futur.blue
objective categorical abstract machine language personal data server
hermes: Update readme
+23
-30
hermes/README.md
+23
-30
hermes/README.md
···
1
# hermes
2
3
-
is a type-safe XRPC client for atproto.
4
5
Hermes provides three components:
6
7
- **hermes** - Core library for making XRPC calls
8
- **hermes-cli** - Code generator for atproto lexicons
9
-
- **hermes_ppx** - PPX extension for ergonomic API calls
10
11
### table of contents
12
13
- [Quick Start](#quick-start)
14
- [Complete Example](#complete-example)
15
-
- [Installation](#installation)
16
- [hermes](#hermes-lib)
17
- [Session Management](#session-management)
18
- [Making XRPC Calls](#making-xrpc-calls)
···
30
31
## quick start
32
33
```ocaml
34
-
open Hermes_lexicons (* generate lexicons using hermes-cli! *)
35
open Lwt.Syntax
36
37
let () = Lwt_main.run begin
···
47
48
## complete example
49
50
```ocaml
51
-
open Hermes_lexicons (* generate lexicons using hermes-cli! *)
52
open Lwt.Syntax
53
54
let main () =
55
(* Set up credential manager with persistence *)
56
-
let manager = Hermes.make_credential_manager ~service:"https://pegasus.example" () in
57
58
Hermes.on_session_update manager (fun session ->
59
let json = Hermes.session_to_yojson session in
···
102
let () = Lwt_main.run (main ())
103
```
104
105
-
## installation
106
-
107
-
Add to your `dune-project`:
108
-
109
-
```lisp
110
-
(depends
111
-
hermes
112
-
hermes_ppx)
113
-
```
114
-
115
<h2 id="hermes-lib">hermes</h2>
116
117
### session management
···
232
lib/generated/
233
├── dune
234
├── lexicons.ml # Re-exports all modules
235
-
└── app/
236
-
└── bsky/
237
-
└── actor/
238
-
└── getProfile.ml
239
```
240
241
Each endpoint module contains:
242
243
```ocaml
244
-
module GetProfile = struct
245
type params = {
246
actor: string;
247
} [@@deriving yojson]
···
278
279
### bytes encoding
280
281
-
Endpoints with non-JSON encoding are automatically detected and handled:
282
283
-
- **Queries with bytes output** (e.g., `com.atproto.sync.getBlob` with `encoding: "*/*"`):
284
-
- Output type is `bytes * string` (data, content_type)
285
-
- Generated code uses `Hermes.query_bytes`
286
-
287
-
- **Procedures with bytes input**:
288
-
- Input is `?input:string` (optional raw bytes)
289
-
- Generated code uses `Hermes.procedure_bytes`
290
291
### union types
292
···
301
302
<h2 id="hermes-ppx">hermes_ppx (PPX extension)</h2>
303
304
-
Transforms `[%xrpc ...]` into generated module calls.
305
306
### setup
307
···
1
# hermes
2
3
+
is a set of libraries that work together to provide a type-safe XRPC client for atproto.
4
5
Hermes provides three components:
6
7
- **hermes** - Core library for making XRPC calls
8
- **hermes-cli** - Code generator for atproto lexicons
9
+
- **hermes_ppx** (optional) - PPX extension for ergonomic API calls
10
11
### table of contents
12
13
- [Quick Start](#quick-start)
14
- [Complete Example](#complete-example)
15
- [hermes](#hermes-lib)
16
- [Session Management](#session-management)
17
- [Making XRPC Calls](#making-xrpc-calls)
···
29
30
## quick start
31
32
+
You'll need your lexicon `.json` files in a directory somewhere. Start by running `hermes-cli` to generate modules from your lexicons.
33
+
34
+
```bash
35
+
hermes-cli generate ./lexicons/ --output=./hermes_lexicons
36
+
```
37
+
38
+
You can find the full set of options for `hermes-cli` [here](#options).
39
+
40
+
A `hermes_lexicons` directory will be created with generated modules for each lexicon found in `./lexicons`. You can now use these modules in your code.
41
+
42
```ocaml
43
+
open Hermes_lexicons (* generated using hermes-cli *)
44
open Lwt.Syntax
45
46
let () = Lwt_main.run begin
···
56
57
## complete example
58
59
+
You can add the `hermes_ppx` extension ([here's how!](#setup)) for more ergonomic API calls.
60
+
61
```ocaml
62
+
open Hermes_lexicons (* generated using hermes-cli *)
63
open Lwt.Syntax
64
65
let main () =
66
(* Set up credential manager with persistence *)
67
+
let manager = Hermes.make_credential_manager ~service:"https://pds.example" () in
68
69
Hermes.on_session_update manager (fun session ->
70
let json = Hermes.session_to_yojson session in
···
113
let () = Lwt_main.run (main ())
114
```
115
116
<h2 id="hermes-lib">hermes</h2>
117
118
### session management
···
233
lib/generated/
234
├── dune
235
├── lexicons.ml # Re-exports all modules
236
+
└── app_bsky_actor_getProfile.ml
237
```
238
239
Each endpoint module contains:
240
241
```ocaml
242
+
module Main = struct
243
type params = {
244
actor: string;
245
} [@@deriving yojson]
···
276
277
### bytes encoding
278
279
+
Endpoints with non-JSON encoding are automatically detected and handled by `hermes-cli`:
280
281
+
- Queries with bytes output (e.g., `com.atproto.sync.getBlob`): output is `bytes * string` (data, content_type)
282
+
- Procedures with bytes input: input is `?input:bytes`
283
284
### union types
285
···
294
295
<h2 id="hermes-ppx">hermes_ppx (PPX extension)</h2>
296
297
+
transforms `[%xrpc ...]` into generated module calls.
298
299
### setup
300