My agentic slop goes here. Not intended for anyone else!
anil.recoil.org
1(** JMAP Search Snippet types and operations.
2
3 This module implements the JMAP SearchSnippet data type as specified in
4 RFC 8621 Section 5. SearchSnippet objects provide highlighted excerpts
5 from email content that match search queries, making it easier for users
6 to preview search results.
7
8 SearchSnippet objects are not stored - they are computed on-demand based
9 on search queries and returned by the SearchSnippet/get method. They
10 contain highlighted portions of matching text from email subjects and bodies.
11
12 @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-5> RFC 8621, Section 5: SearchSnippet
13*)
14
15open Jmap.Methods
16
17(** SearchSnippet object representation.
18
19 Represents highlighted excerpts from email content that match a search query.
20 SearchSnippet objects are keyed by email ID rather than having their own
21 ID property, since they are computed per email for a specific search.
22
23 The snippets contain highlighted portions of matching text, typically
24 using markup like <mark>...</mark> to indicate matched terms.
25
26 @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-5> RFC 8621, Section 5
27*)
28module SearchSnippet : sig
29 (** SearchSnippet object type *)
30 type t
31
32 (** JSON serialization interface *)
33 include Jmap_sigs.JSONABLE with type t := t
34
35 (** Pretty-printing interface *)
36 include Jmap_sigs.PRINTABLE with type t := t
37
38 (** Get the email ID this snippet corresponds to.
39 @return ID of the email that contains the matching content *)
40 val email_id : t -> Jmap.Id.t
41
42 (** Get the highlighted subject snippet.
43 @return Optional highlighted subject text with search matches marked *)
44 val subject : t -> string option
45
46 (** Get the highlighted preview/body snippet.
47 @return Optional highlighted body text excerpt with search matches marked *)
48 val preview : t -> string option
49
50 (** Create a new SearchSnippet object.
51 @param email_id ID of the email containing the matching content
52 @param subject Optional highlighted subject text
53 @param preview Optional highlighted body/preview text
54 @return New SearchSnippet object *)
55 val v :
56 email_id:Jmap.Id.t ->
57 ?subject:string ->
58 ?preview:string ->
59 unit -> t
60end
61
62(** {1 SearchSnippet Methods}
63
64 SearchSnippet only supports the get method - no create, update, destroy,
65 query, or changes operations. Snippets are computed on-demand based on
66 search filters and email content.
67*)
68
69(** Arguments for SearchSnippet/get method.
70
71 Takes a search filter and optional list of email IDs to generate
72 highlighted snippets for emails that match the search criteria.
73
74 @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-5.1> RFC 8621, Section 5.1
75*)
76module Get_args : sig
77 (** SearchSnippet/get arguments *)
78 type t
79
80 (** JSON serialization interface *)
81 include Jmap_sigs.JSONABLE with type t := t
82
83 (** Pretty-printing interface *)
84 include Jmap_sigs.PRINTABLE with type t := t
85
86 (** Get the account ID for the search operation.
87 @return Account where emails will be searched for snippets *)
88 val account_id : t -> Jmap.Id.t
89
90 (** Get the search filter defining what to search for.
91 @return Filter condition that will generate the highlighted snippets *)
92 val filter : t -> Filter.t
93
94 (** Get the specific email IDs to generate snippets for.
95 @return Optional list of email IDs, or None to include all matching emails *)
96 val email_ids : t -> Jmap.Id.t list option
97
98 (** Create SearchSnippet/get arguments.
99 @param account_id Account to search within
100 @param filter Search filter to apply for highlighting
101 @param email_ids Optional specific email IDs to generate snippets for
102 @return SearchSnippet/get arguments *)
103 val v :
104 account_id:Jmap.Id.t ->
105 filter:Filter.t ->
106 ?email_ids:Jmap.Id.t list ->
107 unit -> t
108end
109
110(** Response for SearchSnippet/get method.
111
112 Contains a map of email IDs to their corresponding SearchSnippet objects,
113 along with any email IDs that were requested but not found.
114
115 @see <https://www.rfc-editor.org/rfc/rfc8621.html#section-5.1> RFC 8621, Section 5.1
116*)
117module Get_response : sig
118 (** SearchSnippet/get response *)
119 type t
120
121 (** JSON serialization interface *)
122 include Jmap_sigs.JSONABLE with type t := t
123
124 (** Pretty-printing interface *)
125 include Jmap_sigs.PRINTABLE with type t := t
126
127 (** Get the account ID from the response.
128 @return Account where snippets were generated *)
129 val account_id : t -> Jmap.Id.t
130
131 (** Get the map of email IDs to their search snippets.
132 @return Map containing SearchSnippet objects keyed by email ID *)
133 val list : t -> (string, SearchSnippet.t) Hashtbl.t
134
135 (** Get the list of email IDs that were not found.
136 @return List of requested email IDs that don't exist or don't match the filter *)
137 val not_found : t -> Jmap.Id.t list
138
139 (** Create SearchSnippet/get response.
140 @param account_id Account where snippets were generated
141 @param list Map of email IDs to their SearchSnippet objects
142 @param not_found List of email IDs that were not found
143 @return SearchSnippet/get response *)
144 val v :
145 account_id:Jmap.Id.t ->
146 list:(string, SearchSnippet.t) Hashtbl.t ->
147 not_found:Jmap.Id.t list ->
148 unit -> t
149end
150
151(** {1 Helper Functions}
152
153 Utility functions for working with SearchSnippet objects and
154 processing highlighted content.
155*)
156
157(** Extract matched search terms from highlighted snippet text.
158
159 Parses a snippet string containing highlighted markup (typically
160 <mark>...</mark> tags) and extracts the actual search terms that
161 were matched and highlighted.
162
163 @param snippet Highlighted snippet text with markup
164 @return List of extracted search terms that were highlighted *)
165val extract_matched_terms : string -> string list
166
167(** Create a filter for searching in email body text.
168
169 Generates a search filter that looks for the specified text within
170 email body content. This is commonly used for SearchSnippet/get
171 requests to generate body snippets.
172
173 @param text Text to search for in email bodies
174 @return Filter condition for body text search *)
175val create_body_text_filter : string -> Filter.t
176
177(** Create a comprehensive full-text search filter.
178
179 Generates a search filter that looks for the specified text across
180 multiple email fields including subject, body, and headers. This
181 provides broader search coverage for snippet generation.
182
183 @param text Text to search for across email content
184 @return Filter condition for comprehensive text search *)
185val create_fulltext_filter : string -> Filter.t