Add @upyo/jmap package for JMAP email transport

[dahlia]

Summary

This PR adds @upyo/jmap, a new transport package that implements email sending via the JMAP protocol (RFC 8620/8621). JMAP is a modern, JSON-based protocol designed to replace IMAP and offers advantages like stateless HTTP communication and batch request support.

Closes #10.

Overview

Unlike SMTP which requires maintaining persistent connections, JMAP uses standard HTTP POST requests with JSON payloads. This makes it a natural fit for serverless and edge environments where connection pooling is impractical. The implementation follows the same patterns established by other HTTP-based transports in Upyo (Mailgun, SendGrid, SES).

A key feature of JMAP is its support for batch requests: multiple method calls can be combined into a single HTTP request, with later calls referencing results from earlier ones. The sendMany() method takes advantage of this by batching all emails into a single request, significantly reducing HTTP round-trips when sending multiple messages.

Usage

import { JmapTransport } from "@upyo/jmap";

const transport = new JmapTransport({
  sessionUrl: "https://jmap.example.com/.well-known/jmap",
  bearerToken: "your-token",
});

await transport.send({
  sender: { address: "[email protected]", name: "Sender" },
  recipients: [{ address: "[email protected]" }],
  subject: "Hello via JMAP",
  content: { text: "Hello, World!", html: "<p>Hello, World!</p>" },
});

Features

The transport supports all standard Upyo message features including text/HTML content, attachments (both inline and regular), CC/BCC recipients, reply-to addresses, custom headers, and priority settings. Session information is cached to avoid redundant round-trips, and the transport automatically discovers the mail-capable account and resolves sender identities.

Comparison with original plan

The implementation follows the plan outlined in issue #10 with a few differences:

Aspect	Original plan	Implementation
Authentication	Bearer token only	Bearer token + Basic auth
Session caching	TTL-based option	Per-instance caching
sendMany()	Phase 3 optimization	Fully implemented with batch processing
Delayed send	Phase 4 (optional)	Deferred to future release
Undo support	Phase 4 (optional)	Deferred to future release

The delayed send and undo features were intentionally deferred as they require additional protocol support that not all JMAP servers implement consistently.

Testing

The package includes comprehensive unit tests covering configuration, session management, message conversion, HTTP client behavior, and batch processing. E2E tests run against Stalwart Mail Server in Docker, which is automatically started in CI via docker-compose.

Documentation

• Package README with installation and usage instructions
• VitePress documentation page at docs/transports/jmap.md
• CHANGES.md updated with new package announcement

[codecov]

Welcome to Codecov 🎉

Once you merge this PR into your default branch, you're all set! Codecov will compare coverage reports and display results in all future pull requests.

Thanks for integrating Codecov - We've got you covered ☂️

[Copilot]

Pull request overview

This PR introduces the @upyo/jmap package, implementing email transport via the JMAP protocol (RFC 8620/8621). JMAP is a modern JSON-based protocol designed as an alternative to SMTP/IMAP, offering stateless HTTP communication and batch request capabilities well-suited for serverless environments.

Key Changes:

• Complete JMAP transport implementation with session discovery, identity resolution, and batch processing
• Comprehensive test coverage including unit tests and E2E tests against Stalwart Mail Server
• Full documentation including package README and VitePress guide

Reviewed changes

Copilot reviewed 33 out of 35 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
packages/jmap/src/*.ts	Core transport implementation with config, HTTP client, session management, message conversion, and blob upload
packages/jmap/src/*.test.ts	Comprehensive unit and E2E test suites
packages/jmap/README.md	Package documentation with installation and usage examples
docs/transports/jmap.md	VitePress documentation page with detailed configuration guide
packages/jmap/docker-compose.yml	Stalwart Mail Server setup for E2E testing
.github/workflows/main.yaml	CI integration for automated testing
CHANGES.md	Changelog entry for the new package
pnpm-lock.yaml	Dependency updates including jmap-rfc-types

Files not reviewed (1)

• pnpm-lock.yaml: Language not supported