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