# JMAP Implementation

OCaml implementation of the JMAP protocol (RFC 8620, RFC 8621) with Eio for async I/O.

## Packages

- **jmap**: Unified, ergonomic interface combining all libraries (recommended)
- **jmap-core**: Core JMAP protocol types and parsers (RFC 8620)
- **jmap-mail**: JMAP Mail extension (RFC 8621)
- **jmap-client**: HTTP client for JMAP servers using Eio

## Features

- ✅ **Ergonomic API**: Clean, unified `Jmap` module with short aliases
- ✅ **Type-safe**: Uses GADTs to ensure compile-time correctness
- ✅ Full Eio-based async I/O
- ✅ Uses `Requests` library for HTTP client layer
- ✅ Bearer token and Basic authentication
- ✅ Session management
- ✅ API calls with proper JSON serialization
- ✅ Upload and download support

## Installation

```bash
# Recommended: Install the unified package
opam install jmap

# Or install individual packages for specialized use
opam install jmap-core jmap-mail jmap-client
```

## Quick Start

### Using the Unified API (Recommended)

```ocaml
Eio_main.run @@ fun env ->
Eio.Switch.run @@ fun sw ->

(* Create connection with authentication *)
let conn = Jmap.Connection.bearer_auth ~token:"your-api-token" () in

(* Create client *)
let client = Jmap.Client.create
  ~sw
  ~env
  ~conn
  ~session_url:"https://api.fastmail.com/jmap/session"
  () in

(* Fetch session *)
let session = Jmap.Client.get_session client in
Printf.printf "Username: %s\n" (Jmap.Session.username session);

(* Query emails using typed API *)
let query_req = Jmap.Email.Query.request_v
  ~account_id:(Jmap.Id.of_string account_id)
  ~limit:(Jmap.Primitives.UnsignedInt.of_int 10)
  ()
in

let query_args = Jmap.Email.Query.request_to_json query_req in
let invocation = Jmap.Invocation.make_echo "Email/query" query_args "q1" in
let req = Jmap.Request.make
  ~using:[Jmap.Capability.core; Jmap.Capability.mail]
  [invocation]
in

let resp = Jmap.Client.call client req
```

For more examples and advanced usage, see [USAGE_GUIDE.md](USAGE_GUIDE.md).

## Testing with Fastmail

1. Create an API token at https://www.fastmail.com/settings/security/tokens

2. Save it to `jmap/.api-key`:
   ```bash
   echo "your-api-token-here" > jmap/.api-key
   ```

3. Run the test:
   ```bash
   dune exec jmap/test/test_fastmail.exe
   ```

## Architecture

The library is organized into clean, modular packages:

- ✅ Unified `Jmap` module for ergonomic, everyday use
- ✅ Specialized submodules (`Jmap_core`, `Jmap_mail`) for advanced cases
- ✅ Full Eio integration with structured concurrency
- ✅ Type-safe GADTs for compile-time correctness

## Dependencies

- `eio` - Effects-based direct-style I/O
- `requests` - HTTP client library
- `ezjsonm` / `yojson` - JSON handling
- `cohttp` / `uri` - HTTP utilities