Guidelines for the AI copilot editor.#

Whenever you generate any new OCaml functions, annotate that function's OCamldoc with a "TODO:claude" to indicate it is autogenerated. Do this for every function you generate and not just the header file.

Project structure#

The spec/rfc8620.txt is the core JMAP protocol, which we are aiming to implement in OCaml code in this project. We must accurately capture the specification in the OCaml interface and never violate it without clear indication.

Coding Instructions#

Read your instructions from this file, and mark successfully completed instructions with DONE so that you will know what to do next when reinvoked in the future. If you only partially complete the task, then add an extra step with TODO and the remaining work.

DONE Define core OCaml type definitions corresponding to the JMAP protocol specification, in a new Jmap.Types module.
DONE Add a Jmap.Api module to make JMAP API requests over HTTP and parse the responses into the Jmap.Types. Used Cohttp_lwt_unix for the HTTP library. Note: There is a compilation issue with the current ezjsonm package on the system.
DONE Add a Jmap_mail implementation that follows spec/rfc8621.txt as part of a separate package. It should use the Jmap module and extend it appropriately.
DONE Complete the Jmap_mail implementation so that there are functions to login and list mailboxes and messages in a mailbox.
DONE Fastmail provides me with an API token to login via JMAP rather than username and password. Add the appropriate support for this into their API, which is also explained over at https://www.fastmail.com/dev/. The summary is that the auth token needs to add an Authorization header set to "Bearer {value}", where {value} is the value of the token to your API request.
DONE Add an example fastmail_list binary that will use the authentication token from a JMAP_API_TOKEN env variable and connect to the Fastmail endpoint at https://api.fastmail.com/jmap/session and list the last 100 email with subjects and sender details to stdout.
DONE Examine the implementation of fastmail-list as well as the JMAP specs, and add better typed handling of string responses such as "urn:ietf:params:jmap:mail". Add these to either Jmap_mail or Jmap modules as appropriate.
DONE Move some of the debug print messages into a debug logging mode, and ensure that sensitive API tokens are never printed but redacted instead. Modify the fastmail-list binary to optionally list only unread messages, and also list the JMAP labels associated with each message.
DONE Read the mailbox attribute spec in specs/ and add a typed interface to the JMAP labels defined in there.
DONE Integrate the human-readable keyword and label printing into fastmail-list.
DONE Add an OCaml interface to compose result references together explicitly into a single request, from reading the specs.
DONE Extend the fastmail-list to filter messages displays by email address of the sender. This may involve adding logic to parse email addresses; if so, add this logic into the Jmap_mail library.
DONE Refine the ocamldoc in the interfaces to include documentation for every record field and function by summarising the relevant part of the spec. Also include a cross reference URL where relevant by linking to a URL of the form "https://datatracker.ietf.org/doc/html/rfc8620#section-1.1" for the online version of the RFCs stored in specs/
Add an ocamldoc-format tutorial on how to use the library to index.mld along with cross references into the various libraries. Put corresponding executable files into bin/ so that they can be build tested and run as well. Assume the pattern of the JMAP_API_TOKEN environment variable being set can be counted on to be present when they are run.