@dxos/plugin-jmap 0.10.0

package/dx.config.ts

@@ -0,0 +1,32 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { Config2 } from '@dxos/app-framework/config';
+import { trim } from '@dxos/util';
+
+export default Config2.make({
+  plugin: {
+    key: 'org.dxos.plugin.jmap',
+    name: 'JMAP',
+    author: 'DXOS',
+    source: 'https://github.com/dxos/dxos/tree/main/packages/plugins/plugin-jmap',
+    description: trim`
+      Syncs mail from any JMAP server (RFC 8620/8621) into a local-first Mailbox. Fastmail is the
+      canonical provider; the session is discovered at the well-known JMAP endpoint on the host you
+      supply.
+
+      Headless: this plugin contributes the JMAP connector, its credential form, and the sync, send
+      and materialize operations. The mailbox itself, its UI, and the provider-agnostic sync harness
+      belong to the Inbox plugin, which this one depends on.
+
+      Credentials are a host, an account email, and a Bearer API token, validated against the live
+      session when the form is submitted — no OAuth. Sync is incremental: after the first run the
+      server's state string drives a bounded delta per run, and folder and keyword changes reconcile
+      against messages already in the feed.
+    `,
+    dependsOn: ['org.dxos.plugin.inbox'],
+    icon: { key: 'ph--envelope-simple-open--regular', hue: 'green' },
+    tags: ['alpha', 'connector'],
+  },
+});

package/package.json

@@ -0,0 +1,121 @@
+{
+  "name": "@dxos/plugin-jmap",
+  "version": "0.10.0",
+  "description": "DXOS plugin that syncs mail from a JMAP server (RFC 8620/8621) into a Mailbox.",
+  "homepage": "https://dxos.org",
+  "bugs": "https://github.com/dxos/dxos/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dxos/dxos"
+  },
+  "license": "FSL-1.1-Apache-2.0",
+  "author": "DXOS.org",
+  "sideEffects": true,
+  "type": "module",
+  "imports": {
+    "#apis": {
+      "source": "./src/apis/index.ts",
+      "types": "./dist/types/src/apis/index.d.ts",
+      "default": "./dist/lib/apis.mjs"
+    },
+    "#capabilities": {
+      "source": "./src/capabilities/index.ts",
+      "types": "./dist/types/src/capabilities/index.d.ts",
+      "default": "./dist/lib/capabilities.mjs"
+    },
+    "#meta": {
+      "source": "./src/meta.ts",
+      "types": "./dist/types/src/meta.d.ts",
+      "default": "./dist/lib/meta.mjs"
+    },
+    "#operations": {
+      "source": "./src/operations/index.ts",
+      "types": "./dist/types/src/operations/index.d.ts",
+      "default": "./dist/lib/operations.mjs"
+    },
+    "#plugin": {
+      "source": "./src/JmapPlugin.ts",
+      "types": "./dist/types/src/JmapPlugin.d.ts",
+      "default": "./dist/lib/JmapPlugin.mjs"
+    },
+    "#services": {
+      "source": "./src/services/index.ts",
+      "types": "./dist/types/src/services/index.d.ts",
+      "default": "./dist/lib/services.mjs"
+    },
+    "#translations": {
+      "source": "./src/translations.ts",
+      "types": "./dist/types/src/translations.d.ts",
+      "default": "./dist/lib/translations.mjs"
+    }
+  },
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/types/src/index.d.ts",
+      "import": "./dist/lib/index.mjs"
+    },
+    "./plugin": {
+      "source": "./src/plugin.ts",
+      "types": "./dist/types/src/plugin.d.ts",
+      "import": "./dist/lib/plugin.mjs"
+    },
+    "./testing": {
+      "source": {
+        "node": "./src/testing/node.ts",
+        "default": "./src/testing/index.ts"
+      },
+      "types": "./dist/types/src/testing/index.d.ts",
+      "node": "./dist/lib/testing/node.mjs",
+      "default": "./dist/lib/testing.mjs"
+    },
+    "./translations": {
+      "source": "./src/translations.ts",
+      "types": "./dist/types/src/translations.d.ts",
+      "import": "./dist/lib/translations.mjs"
+    }
+  },
+  "types": "dist/types/src/index.d.ts",
+  "files": [
+    "dist",
+    "dx.config.ts",
+    "src"
+  ],
+  "dependencies": {
+    "date-fns": "^3.6.0",
+    "@dxos/app-framework": "0.11.1",
+    "@dxos/app-toolkit": "0.11.1",
+    "@dxos/effect": "0.11.1",
+    "@dxos/extractor-lib": "0.11.1",
+    "@dxos/compute-runtime": "0.11.1",
+    "@dxos/echo": "0.11.1",
+    "@dxos/keys": "0.11.1",
+    "@dxos/link": "0.11.1",
+    "@dxos/errors": "0.11.1",
+    "@dxos/extractor": "0.11.1",
+    "@dxos/log": "0.11.1",
+    "@dxos/plugin-inbox": "0.11.1",
+    "@dxos/pipeline": "0.11.1",
+    "@dxos/types": "0.11.1",
+    "@dxos/util": "0.11.1",
+    "@dxos/plugin-connector": "0.11.1",
+    "@dxos/pipeline-email": "0.11.1",
+    "@dxos/compute": "0.11.1",
+    "@dxos/schema": "0.11.1"
+  },
+  "devDependencies": {
+    "@effect/platform": "0.96.2",
+    "@effect/vitest": "0.29.0",
+    "effect": "3.21.4",
+    "vite": "^8.1.4",
+    "@dxos/random": "0.11.1",
+    "@dxos/echo-client": "0.11.1"
+  },
+  "peerDependencies": {
+    "@effect/platform": "0.96.2",
+    "effect": "3.21.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/JmapPlugin.ts

@@ -0,0 +1,25 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Plugin from '@dxos/app-framework/Plugin';
+import * as AppCapability from '@dxos/app-toolkit/AppCapability';
+
+import { Connector, MailSend, OperationHandler } from '#capabilities';
+import { meta } from '#meta';
+import { translations } from '#translations';
+
+/**
+ * Headless mail provider: contributes the JMAP connector, its send-routing entry, and the sync/send/
+ * materialize handlers. Every UI surface, the `Mailbox` type, and the sync harness these handlers run
+ * against belong to `@dxos/plugin-inbox`.
+ */
+export const JmapPlugin = Plugin.define(meta).pipe(
+  Plugin.addModule(OperationHandler),
+  Plugin.addModule(AppCapability.translations(translations)),
+  Plugin.addModule(Connector),
+  Plugin.addModule(MailSend),
+  Plugin.make,
+);
+
+export default JmapPlugin;

package/src/apis/Jmap/api.ts

@@ -0,0 +1,138 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as HttpClient from '@effect/platform/HttpClient';
+import * as HttpClientRequest from '@effect/platform/HttpClientRequest';
+import * as HttpClientResponse from '@effect/platform/HttpClientResponse';
+import * as Effect from 'effect/Effect';
+import * as Schedule from 'effect/Schedule';
+import * as Schema from 'effect/Schema';
+
+import { withAuthorization } from '@dxos/compute-runtime';
+
+import { JmapApiError } from '../../errors';
+import { JmapCredentials } from '../../services/jmap-credentials';
+import { MethodError, Response, Session } from './types';
+
+/** Shared per-attempt timeout/retry policy for JMAP HTTP requests (session, batched API, blob download). */
+export const REQUEST_TIMEOUT = '10 seconds';
+export const REQUEST_RETRY = Schedule.exponential(1_000).pipe(Schedule.compose(Schedule.recurs(3)));
+
+// Retry transient failures (network, 5xx, timeout) but not 4xx — a bad host/token or malformed
+// request will fail identically on retry, so retrying only adds latency.
+export const shouldRetry = (error: unknown): boolean =>
+  !(error instanceof JmapApiError && error.status !== undefined && error.status >= 400 && error.status < 500);
+
+/** Capability set for read/write mail requests. */
+export const MAIL_CAPABILITIES = ['urn:ietf:params:jmap:core', 'urn:ietf:params:jmap:mail'] as const;
+/** Capability set including submission, required to send mail. */
+export const SUBMISSION_CAPABILITIES = [...MAIL_CAPABILITIES, 'urn:ietf:params:jmap:submission'] as const;
+
+/** A single `[methodName, args, callId]` invocation in a batched request. */
+export type MethodCall = readonly [string, unknown, string];
+
+/** A batched JMAP API request body (RFC 8620 §3.3). */
+export type RequestBody = {
+  readonly using: readonly string[];
+  readonly methodCalls: readonly MethodCall[];
+};
+
+/**
+ * Discovers the JMAP session: `GET https://${host}/.well-known/jmap` (the well-known URL
+ * 302-redirects to the session resource, which `fetch` follows). Yields `apiUrl` +
+ * `primaryAccounts`. Tracer disabled (Effect + CORS: https://github.com/Effect-TS/effect/issues/4568).
+ */
+export const getSession: Effect.Effect<Session, JmapApiError, HttpClient.HttpClient | JmapCredentials> = Effect.gen(
+  function* () {
+    const { host, token } = yield* JmapCredentials;
+    const httpClient = yield* HttpClient.HttpClient.pipe(Effect.map(withAuthorization(token, 'Bearer')));
+    const httpClientWithTracerDisabled = httpClient.pipe(HttpClient.withTracerDisabledWhen(() => true));
+
+    return yield* HttpClientRequest.get(`https://${host}/.well-known/jmap`).pipe(
+      HttpClientRequest.setHeader('accept', 'application/json'),
+      httpClientWithTracerDisabled.execute,
+      Effect.flatMap(decodeJsonOrFail(Session)),
+      Effect.timeout(REQUEST_TIMEOUT),
+      Effect.retry({ schedule: REQUEST_RETRY, while: shouldRetry }),
+      Effect.scoped,
+      Effect.withSpan('JmapGetSession'),
+      Effect.mapError(asJmapApiError),
+    );
+  },
+);
+
+/**
+ * Issues a batched JMAP API request (single POST to the session `apiUrl`) and decodes the response
+ * envelope. Read requests retry on transient failure; pass `{ retry: false }` for non-idempotent
+ * writes (draft create + submission) so a retry can't double-send.
+ */
+export const jmapRequest = (
+  apiUrl: string,
+  body: RequestBody,
+  options: { retry?: boolean } = {},
+): Effect.Effect<Response, JmapApiError, HttpClient.HttpClient | JmapCredentials> =>
+  Effect.gen(function* () {
+    const { token } = yield* JmapCredentials;
+    const httpClient = yield* HttpClient.HttpClient.pipe(Effect.map(withAuthorization(token, 'Bearer')));
+    const httpClientWithTracerDisabled = httpClient.pipe(HttpClient.withTracerDisabledWhen(() => true));
+
+    const executed = HttpClientRequest.post(apiUrl).pipe(
+      HttpClientRequest.setHeader('accept', 'application/json'),
+      HttpClientRequest.bodyUnsafeJson(body),
+      httpClientWithTracerDisabled.execute,
+      Effect.flatMap(decodeJsonOrFail(Response)),
+      Effect.timeout(REQUEST_TIMEOUT),
+    );
+
+    return yield* (
+      options.retry === false ? executed : executed.pipe(Effect.retry({ schedule: REQUEST_RETRY, while: shouldRetry }))
+    ).pipe(Effect.scoped, Effect.withSpan('JmapApiRequest'), Effect.mapError(asJmapApiError));
+  });
+
+/**
+ * Extracts and decodes the result for a given `callId` from a response envelope. A method-level
+ * `["error", …]` response (or a decode failure) becomes a typed {@link JmapApiError}.
+ */
+export const getMethodResponse = <A, I, R>(
+  response: Response,
+  callId: string,
+  schema: Schema.Schema<A, I, R>,
+): Effect.Effect<A, JmapApiError, R> => {
+  const entry = response.methodResponses.find((methodResponse) => methodResponse[2] === callId);
+  if (!entry) {
+    return Effect.fail(new JmapApiError(undefined, `No method response for call ${callId}.`));
+  }
+
+  const [name, args] = entry;
+  if (name === 'error') {
+    return Schema.decodeUnknown(MethodError)(args).pipe(
+      Effect.matchEffect({
+        onFailure: () => Effect.fail(new JmapApiError(undefined, `JMAP method error (${callId}).`)),
+        onSuccess: (error) => Effect.fail(new JmapApiError(undefined, error.description ?? error.type, error.type)),
+      }),
+    );
+  }
+
+  return Schema.decodeUnknown(schema)(args).pipe(Effect.mapError(asJmapApiError));
+};
+
+/** Decodes a 2xx JSON body against `schema`; a >=400 status fails with the (truncated) body text. */
+const decodeJsonOrFail =
+  <A, I, R>(schema: Schema.Schema<A, I, R>) =>
+  (response: HttpClientResponse.HttpClientResponse): Effect.Effect<A, JmapApiError, R> =>
+    Effect.gen(function* () {
+      if (response.status >= 400) {
+        const body = yield* response.text;
+        return yield* Effect.fail(new JmapApiError(response.status, truncate(body)));
+      }
+      return yield* HttpClientResponse.schemaBodyJson(schema)(response);
+    }).pipe(Effect.mapError(asJmapApiError));
+
+/** Collapses transport/decode failures (HttpClientError, ParseError, timeout) into a typed JmapApiError. */
+const asJmapApiError = (error: unknown): JmapApiError =>
+  error instanceof JmapApiError
+    ? error
+    : new JmapApiError(undefined, error instanceof Error ? error.message : String(error));
+
+const truncate = (text: string, max = 500): string => (text.length > max ? `${text.slice(0, max)}…` : text);

package/src/apis/Jmap/index.ts

@@ -0,0 +1,6 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './api';
+export * from './types';

package/src/apis/Jmap/types.ts

@@ -0,0 +1,86 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+
+//
+// Shared JMAP core schemas (RFC 8620). These are capability-agnostic — they apply to mail, calendars,
+// and contacts alike.
+//
+
+/** Session object returned from `https://${host}/.well-known/jmap` (RFC 8620 §2). */
+export const Session = Schema.Struct({
+  /** Endpoint for all subsequent API requests. */
+  apiUrl: Schema.String,
+  /**
+   * URI Template (RFC 6570) for blob downloads, with `accountId`/`blobId`/`type`/`name` variables
+   * (RFC 8620 §6.2). Required, matching the spec — every real JMAP session advertises one.
+   */
+  downloadUrl: Schema.String,
+  /** Authenticated username (used to seed the connection account when the form leaves it blank). */
+  username: Schema.optional(Schema.String),
+  /** Capability urn → primary account id (e.g. `urn:ietf:params:jmap:mail`). */
+  primaryAccounts: Schema.Record({ key: Schema.String, value: Schema.String }),
+  accounts: Schema.optional(Schema.Record({ key: Schema.String, value: Schema.Unknown })),
+  capabilities: Schema.optional(Schema.Record({ key: Schema.String, value: Schema.Unknown })),
+  state: Schema.optional(Schema.String),
+});
+export type Session = Schema.Schema.Type<typeof Session>;
+
+/** A method-level error response: `["error", { type, description }, callId]` (RFC 8620 §3.6.1). */
+export const MethodError = Schema.Struct({
+  type: Schema.String,
+  description: Schema.optional(Schema.NullOr(Schema.String)),
+});
+export type MethodError = Schema.Schema.Type<typeof MethodError>;
+
+/** A single `[name, args, callId]` invocation result; `args` is decoded per-method by the caller. */
+export const MethodResponse = Schema.Tuple(Schema.String, Schema.Unknown, Schema.String);
+export type MethodResponse = Schema.Schema.Type<typeof MethodResponse>;
+
+/** The top-level response envelope of a batched API request (RFC 8620 §3.3). */
+export const Response = Schema.Struct({
+  methodResponses: Schema.Array(MethodResponse),
+  sessionState: Schema.optional(Schema.String),
+});
+export type Response = Schema.Schema.Type<typeof Response>;
+
+//
+// `Email/query` filter (RFC 8621 §4.4.1). Constructed client-side (never decoded), so these are plain
+// types rather than Schemas. Shared here because future calendar/contacts filters share the same
+// AND/OR/NOT operator structure (RFC 8620 §5.5).
+//
+
+/** A single filter condition; all present properties must match. */
+export type FilterCondition = {
+  readonly inMailbox?: string;
+  readonly inMailboxOtherThan?: readonly string[];
+  readonly before?: string;
+  readonly after?: string;
+  readonly minSize?: number;
+  readonly maxSize?: number;
+  readonly hasKeyword?: string;
+  readonly notKeyword?: string;
+  readonly allInThreadHaveKeyword?: string;
+  readonly someInThreadHaveKeyword?: string;
+  readonly noneInThreadHaveKeyword?: string;
+  readonly text?: string;
+  readonly from?: string;
+  readonly to?: string;
+  readonly cc?: string;
+  readonly bcc?: string;
+  readonly subject?: string;
+  readonly body?: string;
+  readonly header?: readonly string[];
+  readonly hasAttachment?: boolean;
+};
+
+/** Combines sub-filters (RFC 8620 §5.5). */
+export type FilterOperator = {
+  readonly operator: 'AND' | 'OR' | 'NOT';
+  readonly conditions: readonly Filter[];
+};
+
+/** An `Email/query` filter: a single condition or an AND/OR/NOT combination. */
+export type Filter = FilterCondition | FilterOperator;