This repository has no description
1(*---------------------------------------------------------------------------
2 Copyright (c) 2025 Anil Madhavapeddy. All rights reserved.
3 SPDX-License-Identifier: ISC
4 ---------------------------------------------------------------------------*)
5
6(** JMAP method invocation as defined in RFC 8620 Section 3.2
7
8 @canonical Jmap.Proto.Invocation *)
9
10(** {1 Result References} *)
11
12(** A reference to a result from a previous method call.
13
14 Used for back-referencing values within a single request.
15 The path is a JMAP extended JSON Pointer (RFC 8620 Section 3.7)
16 which may contain [*] wildcards for array mapping. *)
17type result_reference = {
18 result_of : string;
19 (** The method call id to reference. *)
20 name : string;
21 (** The method name that was called. *)
22 path : Json_pointer.Jmap.t;
23 (** A JMAP extended JSON Pointer to the value within the result.
24 May contain [*] wildcards for mapping through arrays. *)
25}
26
27val result_reference :
28 result_of:string ->
29 name:string ->
30 path:Json_pointer.Jmap.t ->
31 result_reference
32
33val result_reference_of_strings :
34 result_of:string ->
35 name:string ->
36 path:string ->
37 result_reference
38(** [result_reference_of_strings] creates a result reference, parsing
39 the path string into a JMAP pointer.
40 @raise Jsont.exception-Error if the path is not a valid JMAP pointer. *)
41
42val result_reference_jsont : result_reference Jsont.t
43
44(** {2 Typed Extraction}
45
46 These functions extract typed values from method responses using
47 the result reference's path. *)
48
49val resolve_ids :
50 result_reference ->
51 responses:(string * string * Jsont.json) list ->
52 string list
53(** [resolve_ids ref ~responses] resolves the result reference against
54 the list of previous responses and extracts a list of string IDs.
55
56 [responses] is a list of [(method_call_id, method_name, result_json)]
57 tuples from previously executed method calls.
58
59 This is the most common pattern in JMAP where result references are
60 used to pass IDs between method calls.
61
62 @raise Jsont.exception-Error if resolution fails or the result is not a string list. *)
63
64val resolve :
65 result_reference ->
66 responses:(string * string * Jsont.json) list ->
67 'a Jsont.t ->
68 'a
69(** [resolve ref ~responses codec] resolves the result reference and
70 decodes the extracted value with [codec].
71
72 @raise Jsont.exception-Error if resolution fails or decoding fails. *)
73
74(** {1 Invocations} *)
75
76(** A method invocation.
77
78 In JSON, this is represented as a 3-element array:
79 ["methodName", {args}, "methodCallId"] *)
80type t = {
81 name : string;
82 (** The method name, e.g., "Email/get". *)
83 arguments : Jsont.json;
84 (** The method arguments as a JSON object. *)
85 method_call_id : string;
86 (** Client-specified identifier for this call. *)
87}
88
89val create :
90 name:string ->
91 arguments:Jsont.json ->
92 method_call_id:string ->
93 t
94(** [create ~name ~arguments ~method_call_id] creates an invocation. *)
95
96val name : t -> string
97val arguments : t -> Jsont.json
98val method_call_id : t -> string
99
100val jsont : t Jsont.t
101(** JSON codec for invocations (as 3-element array). *)
102
103(** {1 Typed Invocation Helpers} *)
104
105val make_get :
106 method_call_id:string ->
107 method_name:string ->
108 Proto_method.get_args ->
109 t
110(** [make_get ~method_call_id ~method_name args] creates a /get invocation. *)
111
112val make_changes :
113 method_call_id:string ->
114 method_name:string ->
115 Proto_method.changes_args ->
116 t
117(** [make_changes ~method_call_id ~method_name args] creates a /changes invocation. *)
118
119val make_query :
120 method_call_id:string ->
121 method_name:string ->
122 filter_cond_jsont:'f Jsont.t ->
123 'f Proto_method.query_args ->
124 t
125(** [make_query ~method_call_id ~method_name ~filter_cond_jsont args] creates a /query invocation. *)