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/
DONE 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.
DONE Add a README.md to this repository that describes what this is. Note explicitly in the README that this is largely an AI-generated interface and has not been audited carefully.
DONE Ensure examples use the proper higher-level API functions from the library instead of manually constructing low-level requests. Particularly, the fastmail_list binary should demonstrate the recommended way to use the library with Jmap_mail's API.
DONE Add helper functions to Jmap.Api such as string_of_error and pp_error to format errors consistently. Updated the fastmail_list binary to use these functions instead of duplicating error handling code.
DONE Add support for JMAP email submission to the library, and create a fastmail-send that accepts a list of to: on the CLI as arguments and a subject on the CLI and reads in the message body
Potential future work:
- Add helper functions for more complex filtering of emails
- Implement support for Email/copy and Email/import methods
- Add functions for managing identities and vacation responses
- Add proper testing framework with mocked JMAP server responses
- Create more examples of different JMAP operations (creating/updating mailboxes and emails)
- Add support for other JMAP extensions like Contacts and Calendars