anil.recoil.org
OCaml bindings to the Typesense embeddings search API
1(*---------------------------------------------------------------------------
2 Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.
3 SPDX-License-Identifier: ISC
4 ---------------------------------------------------------------------------*)
5
6(** Session management for Typesense CLI with profile support.
7
8 This module provides session persistence for Typesense authentication
9 using API keys. Sessions are stored in profile-specific directories
10 under [~/.config/typesense/profiles/<profile>/session.json].
11
12 {2 Directory Structure}
13
14 {v
15 ~/.config/typesense/
16 config.json # Stores current_profile setting
17 profiles/
18 default/
19 session.json # Session for "default" profile
20 prod/
21 session.json # Session for "prod" profile
22 v}
23
24 {[
25 (* Login with API key *)
26 let session = Session.create
27 ~server_url:"http://localhost:8108"
28 ~api_key:"xyz"
29 () in
30 Session.save fs ~profile:"default" session
31 ]} *)
32
33(** {1 Types} *)
34
35type t
36(** Session data. *)
37
38val jsont : t Jsont.t
39(** JSON codec for sessions. *)
40
41(** {1 Session Construction} *)
42
43val create : server_url:string -> api_key:string -> unit -> t
44(** [create ~server_url ~api_key ()] creates a new session with the current timestamp. *)
45
46(** {1 Session Accessors} *)
47
48val server_url : t -> string
49(** [server_url t] returns the server URL. *)
50
51val api_key : t -> string
52(** [api_key t] returns the API key. *)
53
54val created_at : t -> string
55(** [created_at t] returns the creation timestamp (RFC 3339). *)
56
57(** {1 Profile Management} *)
58
59val default_profile : string
60(** The default profile name (["default"]). *)
61
62val get_current_profile : Eio.Fs.dir_ty Eio.Path.t -> string
63(** [get_current_profile fs] returns the current profile name. Returns
64 {!default_profile} if no profile has been set. *)
65
66val set_current_profile : Eio.Fs.dir_ty Eio.Path.t -> string -> unit
67(** [set_current_profile fs profile] sets the current profile. *)
68
69val list_profiles : Eio.Fs.dir_ty Eio.Path.t -> string list
70(** [list_profiles fs] returns all profiles that have sessions.
71 Returns profile names sorted alphabetically. *)
72
73(** {1 Directory Paths} *)
74
75val base_config_dir : Eio.Fs.dir_ty Eio.Path.t -> Eio.Fs.dir_ty Eio.Path.t
76(** [base_config_dir fs] returns the base config directory
77 ([~/.config/typesense]), creating it if needed. *)
78
79val config_dir :
80 Eio.Fs.dir_ty Eio.Path.t ->
81 ?profile:string ->
82 unit ->
83 Eio.Fs.dir_ty Eio.Path.t
84(** [config_dir fs ?profile ()] returns the config directory for a
85 profile, creating it if needed.
86 @param profile Profile name (default: current profile) *)
87
88(** {1 Session Persistence} *)
89
90val save : Eio.Fs.dir_ty Eio.Path.t -> ?profile:string -> t -> unit
91(** [save fs ?profile session] saves the session.
92 @param profile Profile name (default: current profile) *)
93
94val load : Eio.Fs.dir_ty Eio.Path.t -> ?profile:string -> unit -> t option
95(** [load fs ?profile ()] loads a saved session.
96 @param profile Profile name (default: current profile) *)
97
98val clear : Eio.Fs.dir_ty Eio.Path.t -> ?profile:string -> unit -> unit
99(** [clear fs ?profile ()] removes the saved session.
100 @param profile Profile name (default: current profile) *)
101
102(** {1 Session Utilities} *)
103
104val pp : t Fmt.t
105(** Pretty-print a session. *)