Merge pull request #20 from dahlia/jmap

Add @upyo/jmap package for JMAP email transport

Author: dahlia

.github/workflows/main.yaml

@@ -24,6 +24,10 @@ jobs:
       MAILPIT_SMTP_PORT: 1025
       MAILPIT_SMTP_SECURE: "false"
       MAILPIT_API_URL: http://localhost:8025
+      STALWART_SESSION_URL: http://localhost:8080/jmap/session
+      STALWART_USERNAME: test@mail.example.com
+      STALWART_PASSWORD: password123
+      STALWART_BASE_URL: http://localhost:8080
       MAILGUN_KEY: ${{ secrets.MAILGUN_KEY }}
       MAILGUN_FROM: ${{ secrets.MAILGUN_FROM }}
       MAILGUN_TO: ${{ secrets.MAILGUN_TO }}
@@ -44,6 +48,10 @@ jobs:
     - uses: actions/setup-node@v4
       with:
         node-version: latest
+    - name: Start Stalwart
+      run: docker compose -f packages/jmap/docker-compose.yml up -d
+    - name: Setup Stalwart test accounts
+      run: ./packages/jmap/scripts/setup-stalwart.sh
     - run: pnpm run -r test
 
   test-deno:
@@ -68,6 +76,10 @@ jobs:
       MAILPIT_SMTP_PORT: 1025
       MAILPIT_SMTP_SECURE: "false"
       MAILPIT_API_URL: http://localhost:8025
+      STALWART_SESSION_URL: http://localhost:8080/jmap/session
+      STALWART_USERNAME: test@mail.example.com
+      STALWART_PASSWORD: password123
+      STALWART_BASE_URL: http://localhost:8080
       MAILGUN_KEY: ${{ secrets.MAILGUN_KEY }}
       MAILGUN_FROM: ${{ secrets.MAILGUN_FROM }}
       MAILGUN_TO: ${{ secrets.MAILGUN_TO }}
@@ -84,6 +96,10 @@ jobs:
     - uses: denoland/setup-deno@v2
       with:
         deno-version: v2.x
+    - name: Start Stalwart
+      run: docker compose -f packages/jmap/docker-compose.yml up -d
+    - name: Setup Stalwart test accounts
+      run: ./packages/jmap/scripts/setup-stalwart.sh
     - run: deno task test --coverage --junit-path=junit.xml
     - if: ${{ !cancelled() }}
       uses: codecov/test-results-action@v1
@@ -117,6 +133,10 @@ jobs:
       MAILPIT_SMTP_PORT: 1025
       MAILPIT_SMTP_SECURE: "false"
       MAILPIT_API_URL: http://localhost:8025
+      STALWART_SESSION_URL: http://localhost:8080/jmap/session
+      STALWART_USERNAME: test@mail.example.com
+      STALWART_PASSWORD: password123
+      STALWART_BASE_URL: http://localhost:8080
       MAILGUN_KEY: ${{ secrets.MAILGUN_KEY }}
       MAILGUN_FROM: ${{ secrets.MAILGUN_FROM }}
       MAILGUN_TO: ${{ secrets.MAILGUN_TO }}
@@ -137,6 +157,10 @@ jobs:
     - uses: oven-sh/setup-bun@v2
       with:
         bun-version: 1.2.22
+    - name: Start Stalwart
+      run: docker compose -f packages/jmap/docker-compose.yml up -d
+    - name: Setup Stalwart test accounts
+      run: ./packages/jmap/scripts/setup-stalwart.sh
     - run: pnpm run -r test:bun
 
   check:

CHANGES.md

@@ -36,6 +36,27 @@ To be released.
 
 [#18]: https://github.com/dahlia/upyo/issues/18
 
+### @upyo/jmap
+
+ -  Added JMAP transport for sending emails via JMAP protocol.  [[#10]]
+
+    JMAP (JSON Meta Application Protocol) is a modern, efficient protocol for
+    email access and submission, defined in RFC 8620 (core) and RFC 8621 (mail).
+    This transport provides:
+
+     -  Automatic session discovery and caching
+     -  Automatic identity resolution from sender email
+     -  Bearer token authentication
+     -  Exponential backoff retry with configurable attempts
+     -  Request timeout and AbortSignal support
+     -  Text and HTML message content (multipart/alternative)
+     -  Priority headers (X-Priority, Importance)
+     -  Custom headers
+     -  File attachments via blob upload
+     -  Inline attachments (multipart/related)
+
+[#10]: https://github.com/dahlia/upyo/issues/10
+
 ### @upyo/resend
 
  -  Added support for user-provided idempotency keys via `Message.idempotencyKey`.

README.md

@@ -68,6 +68,7 @@ sending messages.  The following is a list of the available packages:
 | ----------------------------------------------- | ------------------------------ | ------------------------------ | -------------------------------------------------- |
 | [@upyo/core](/packages/core/)                   | [JSR][jsr:@upyo/core]          | [npm][npm:@upyo/core]          | Shared types and interfaces for email messages     |
 | [@upyo/smtp](/packages/smtp/)                   | [JSR][jsr:@upyo/smtp]          | [npm][npm:@upyo/smtp]          | SMTP transport                                     |
+| [@upyo/jmap](/packages/jmap/)                   | [JSR][jsr:@upyo/jmap]          | [npm][npm:@upyo/jmap]          | [JMAP] transport (RFC 8620/8621)                   |
 | [@upyo/mailgun](/packages/mailgun/)             | [JSR][jsr:@upyo/mailgun]       | [npm][npm:@upyo/mailgun]       | [Mailgun] transport                                |
 | [@upyo/plunk](/packages/plunk/)                 | [JSR][jsr:@upyo/plunk]         | [npm][npm:@upyo/plunk]         | [Plunk] transport                                  |
 | [@upyo/resend](/packages/resend/)               | [JSR][jsr:@upyo/resend]        | [npm][npm:@upyo/resend]        | [Resend] transport                                 |
@@ -80,6 +81,8 @@ sending messages.  The following is a list of the available packages:
 [npm:@upyo/core]: https://www.npmjs.com/package/@upyo/core
 [jsr:@upyo/smtp]: https://jsr.io/@upyo/smtp
 [npm:@upyo/smtp]: https://www.npmjs.com/package/@upyo/smtp
+[jsr:@upyo/jmap]: https://jsr.io/@upyo/jmap
+[npm:@upyo/jmap]: https://www.npmjs.com/package/@upyo/jmap
 [jsr:@upyo/mailgun]: https://jsr.io/@upyo/mailgun
 [npm:@upyo/mailgun]: https://www.npmjs.com/package/@upyo/mailgun
 [jsr:@upyo/plunk]: https://jsr.io/@upyo/plunk
@@ -94,6 +97,7 @@ sending messages.  The following is a list of the available packages:
 [npm:@upyo/opentelemetry]: https://www.npmjs.com/package/@upyo/opentelemetry
 [jsr:@upyo/mock]: https://jsr.io/@upyo/mock
 [npm:@upyo/mock]: https://www.npmjs.com/package/@upyo/mock
+[JMAP]: https://jmap.io/
 [Mailgun]: https://www.mailgun.com/
 [Plunk]: https://www.useplunk.com/
 [Resend]: https://resend.com/

deno.lock

@@ -12,6 +12,7 @@ import llmstxt from "vitepress-plugin-llms";
 
 const packages: readonly string[] = [
   "core",
+  "jmap",
   "mailgun",
   "plunk",
   "resend",
@@ -22,13 +23,17 @@ const packages: readonly string[] = [
 const jsrRefPlugins: any[] = [];
 
 for (const pkg of packages) {
-  jsrRefPlugins.push(
-    await jsrRef({
-      package: `@upyo/${pkg}`,
-      version: process.env.JSR_REF_VERSION ?? "unstable",
-      cachePath: `.jsr-cache-${pkg}.json`,
-    }),
-  );
+  try {
+    jsrRefPlugins.push(
+      await jsrRef({
+        package: `@upyo/${pkg}`,
+        version: process.env.JSR_REF_VERSION ?? "unstable",
+        cachePath: `.jsr-cache-${pkg}.json`,
+      }),
+    );
+  } catch {
+    // Ignore errors for packages not yet published to JSR
+  }
 }
 
 let extraNav: { text: string; link: string }[] = [];
@@ -67,6 +72,7 @@ const NAV = [
     text: "Transports",
     items: [
       { text: "SMTP", link: "/transports/smtp" },
+      { text: "JMAP", link: "/transports/jmap" },
       { text: "Mailgun", link: "/transports/mailgun" },
       { text: "Plunk", link: "/transports/plunk" },
       { text: "Resend", link: "/transports/resend" },
@@ -83,6 +89,7 @@ const NAV = [
     items: [
       { text: "@upyo/core", link: "https://jsr.io/@upyo/core/doc" },
       { text: "@upyo/smtp", link: "https://jsr.io/@upyo/smtp/doc" },
+      { text: "@upyo/jmap", link: "https://jsr.io/@upyo/jmap/doc" },
       { text: "@upyo/mailgun", link: "https://jsr.io/@upyo/mailgun/doc" },
       { text: "@upyo/plunk", link: "https://jsr.io/@upyo/plunk/doc" },
       { text: "@upyo/resend", link: "https://jsr.io/@upyo/resend/doc" },

docs/.vitepress/config.mts

@@ -8,6 +8,7 @@
     "@shikijs/vitepress-twoslash": "^3.20.0",
     "@types/node": "^24.0.13",
     "@upyo/core": "workspace:",
+    "@upyo/jmap": "workspace:",
     "@upyo/mailgun": "workspace:",
     "@upyo/mock": "workspace:",
     "@upyo/opentelemetry": "workspace:",