OCaml CLI and library to the Karakeep bookmarking app
1# OCaml Karakeep API Client
2
3An OCaml client library for the [Karakeep](https://karakeep.app) bookmark service API.
4Built on [Eio](https://github.com/ocaml-multicore/eio) for structured concurrency with
5a type-safe interface using [jsont](https://erratique.ch/software/jsont) for JSON encoding/decoding.
6
7## Features
8
9- Full API coverage for bookmarks, tags, lists, highlights, and user operations
10- Automatic pagination support
11- Type-safe JSON encoding/decoding with jsont
12- Built on Eio for structured concurrency
13- Cmdliner integration for CLI tools
14
15## Installation
16
17```bash
18opam install karakeep
19```
20
21Or pin the development version:
22
23```bash
24opam pin add karakeep.dev git+https://tangled.org/@anil.recoil.org/ocaml-karakeep.git
25```
26
27## Configuration
28
29The library requires an API key for authentication. You can obtain an API key from your Karakeep instance settings.
30
31## Usage Example
32
33```ocaml
34let () =
35 Eio_main.run @@ fun env ->
36 Eio.Switch.run @@ fun sw ->
37
38 (* Create the client *)
39 let client =
40 Karakeep.create ~sw ~env
41 ~base_url:"https://hoard.recoil.org"
42 ~api_key:"your_api_key"
43 in
44
45 (* Fetch recent bookmarks *)
46 let result = Karakeep.fetch_bookmarks client ~limit:10 () in
47 List.iter (fun bookmark ->
48 let title = Karakeep.bookmark_title bookmark in
49 Printf.printf "- %s\n" title
50 ) result.bookmarks;
51
52 (* Fetch all bookmarks (handles pagination automatically) *)
53 let all_bookmarks = Karakeep.fetch_all_bookmarks client () in
54 Printf.printf "Total bookmarks: %d\n" (List.length all_bookmarks);
55
56 (* Create a new bookmark *)
57 let _new_bookmark =
58 Karakeep.create_bookmark client
59 ~url:"https://ocaml.org"
60 ~title:"OCaml Programming Language"
61 ~tags:["programming"; "ocaml"]
62 ()
63 in
64
65 (* Search bookmarks *)
66 let search_results = Karakeep.search_bookmarks client ~query:"ocaml" () in
67 Printf.printf "Found %d results\n" (List.length search_results.bookmarks)
68```
69
70## Error Handling
71
72All operations may raise `Eio.Io` exceptions with a `Karakeep.E` error payload:
73
74```ocaml
75try
76 let bookmarks = Karakeep.fetch_bookmarks client () in
77 (* ... *)
78with
79| Eio.Io (Karakeep.E err, _) ->
80 Printf.eprintf "Karakeep error: %s\n" (Karakeep.error_to_string err)
81```
82
83## Documentation
84
85- [API Documentation](doc/index.md)
86- Online documentation is generated with `dune build @doc`
87
88## License
89
90ISC License. See [LICENSE.md](LICENSE.md) for details.