@dxos/plugin-jmap 0.10.0

package/src/operations/mail/sync/system-tags.ts

@@ -0,0 +1,24 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import type * as SystemTags from '@dxos/plugin-inbox/SystemTags';
+
+/**
+ * JMAP mailbox role → canonical system tag ({@link SystemTags.SystemTag}). Roles absent here are
+ * intentionally dropped: `archive` is derived as "not in inbox" (Gmail's model), and
+ * `drafts`/`trash`/`junk` are never synced.
+ */
+export const JMAP_ROLE_TAGS: Partial<Record<string, SystemTags.SystemTagId>> = {
+  inbox: 'inbox',
+  sent: 'sent',
+};
+
+/**
+ * JMAP keyword → canonical system tag ({@link SystemTags.SystemTag}). Only `$flagged` (starred) is
+ * projected; read-state (`$seen`) and the rest (`$answered`, `$draft`, `$forwarded`, …) are intentionally
+ * dropped as high-churn and noisier than useful.
+ */
+export const JMAP_KEYWORD_TAGS: Partial<Record<string, SystemTags.SystemTagId>> = {
+  $flagged: 'starred',
+};

package/src/operations/mail/tags.ts

@@ -0,0 +1,29 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Database, Tag } from '@dxos/echo';
+
+import { JMAP_DOMAIN } from '../../constants';
+
+/**
+ * The pre-rename source, matched as a fallback so folders synced before the rename keep their tag
+ * identity instead of being duplicated. Remove one release after landing.
+ */
+const LEGACY_JMAP_TAG_SOURCE = 'org.ietf.jmap.mailbox';
+
+/**
+ * Finds an existing JMAP provider {@link Tag} object by its JMAP mailbox-id foreign key, or creates one
+ * carrying that key ({@link JMAP_DOMAIN}, which also marks it read-only via `Tag.isProviderTag`). Keeps
+ * the folder label in sync with the server on re-sync. Used by `sync/` for custom user folders;
+ * well-known roles map onto canonical system tags instead. Mirrors Gmail's `findOrCreateGmailTag`.
+ */
+export const findOrCreateJmapTag = (
+  db: Database.Database,
+  { id, name }: { id: string; name: string },
+): Promise<Tag.Tag> =>
+  Tag.findOrCreate(db, {
+    key: { source: JMAP_DOMAIN, id },
+    legacyKeys: [{ source: LEGACY_JMAP_TAG_SOURCE, id }],
+    label: name,
+  });

package/src/plugin.ts

@@ -0,0 +1,11 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Plugin from '@dxos/app-framework/Plugin';
+
+import { meta } from './meta';
+
+export const JmapPlugin = Plugin.lazy(meta, () => import('#plugin'));
+
+export { JmapOperationHandlerSet } from './operations';

package/src/services/index.ts

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

package/src/services/jmap-credentials.ts

@@ -0,0 +1,61 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+
+import { Database, type Ref } from '@dxos/echo';
+import { type AccessToken } from '@dxos/link';
+import { log } from '@dxos/log';
+import * as Connection from '@dxos/plugin-connector/Connection';
+
+/**
+ * Credentials needed to talk to a JMAP server: the server `host` (used to discover the session at
+ * `https://${host}/.well-known/jmap`), the optional `account` (email/username for display and
+ * identity matching), and the Bearer `token`.
+ */
+export type Credentials = {
+  readonly host: string;
+  readonly account: string | undefined;
+  readonly token: string;
+};
+
+/**
+ * Service for accessing JMAP credentials.
+ *
+ * Mirrors `GoogleCredentials`: an operation invoked with a `Connection` composes
+ * `fromConnection(ref)`; one invoked with an external-sync cursor composes
+ * `fromAccessToken(cursor.spec.source)` directly (the cursor no longer relates to `Connection`).
+ * Unlike Google, there is no database-credential fallback — a JMAP connection always carries host +
+ * token in its token record.
+ */
+export class JmapCredentials extends Context.Tag('JmapCredentials')<JmapCredentials, Credentials>() {
+  /** Creates a credentials layer from an AccessToken ref. Loads its `source` (host), `account`, `token`. */
+  static fromAccessToken = (accessTokenRef: Ref.Ref<AccessToken.AccessToken>) =>
+    Layer.effect(
+      JmapCredentials,
+      Effect.gen(function* () {
+        const accessToken = yield* Database.load(accessTokenRef);
+        log('using access token', { source: accessToken.source });
+        return { host: accessToken.source, account: accessToken.account, token: accessToken.token };
+      }),
+    );
+
+  /** Creates a credentials layer from a Connection ref. Loads its `accessToken`'s host/account/token. */
+  static fromConnection = (connectionRef: Ref.Ref<Connection.Connection>) =>
+    Layer.effect(
+      JmapCredentials,
+      Effect.gen(function* () {
+        const connection = yield* Database.load(connectionRef);
+        const accessToken = yield* Database.load(connection.accessToken);
+        log('using connection access token', { source: accessToken.source });
+        return { host: accessToken.source, account: accessToken.account, token: accessToken.token };
+      }),
+    );
+
+  /** Creates a credentials layer from explicit values (credential-form validation and tests). */
+  static fromValues = (values: { host: string; account?: string; token: string }) =>
+    Layer.succeed(JmapCredentials, { host: values.host, account: values.account, token: values.token });
+}

package/src/services/jmap-mail-api.ts

@@ -0,0 +1,294 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import type * as HttpClient from '@effect/platform/HttpClient';
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as Predicate from 'effect/Predicate';
+
+import { Jmap, JmapMail } from '../apis';
+import { JmapApiError } from '../errors';
+import { type JmapCredentials } from './jmap-credentials';
+
+/**
+ * The requirements the underlying {@link Jmap}/{@link JmapMail} request functions carry (HTTP client
+ * + JMAP credentials). {@link JmapMailApi.Live} bakes these in so the service methods themselves
+ * require nothing — which is what lets a test satisfy {@link JmapMailApi} with a zero-dependency mock
+ * (no HTTP, no credentials, no live server).
+ */
+type Requirements = HttpClient.HttpClient | JmapCredentials;
+
+/**
+ * Swappable JMAP API surface. `Live` delegates to the real {@link Jmap}/{@link JmapMail} request
+ * functions; tests provide a data-backed mock. Making the JMAP dependency a service (rather than the
+ * sync operation calling `Jmap.*`/`JmapMail.*` and hardcoding `FetchHttpClient.layer` internally) is
+ * what lets the sync run against generated data with no live account — mirrors `GoogleMailApi`.
+ * Every request fails only with {@link JmapApiError}, and methods carry no requirements: `Live`
+ * bakes them in (see {@link Requirements}) so a mock can satisfy the surface with no HTTP or creds.
+ */
+export interface JmapMailApiService {
+  readonly getSession: Effect.Effect<Jmap.Session, JmapApiError>;
+  readonly mailboxGet: (target: JmapMail.Target) => Effect.Effect<JmapMail.MailboxGetResult, JmapApiError>;
+  readonly emailQuery: (
+    target: JmapMail.Target,
+    options?: {
+      filter?: unknown;
+      sort?: readonly { property: string; isAscending?: boolean }[];
+      position?: number;
+      limit?: number;
+      calculateTotal?: boolean;
+    },
+  ) => Effect.Effect<JmapMail.EmailQueryResult, JmapApiError>;
+  readonly emailGet: (
+    target: JmapMail.Target,
+    ids: readonly string[],
+    properties?: readonly string[],
+  ) => Effect.Effect<JmapMail.EmailGetResult, JmapApiError>;
+  readonly emailChanges: (
+    target: JmapMail.Target,
+    sinceState: string,
+    maxChanges?: number,
+  ) => Effect.Effect<JmapMail.EmailChangesResult, JmapApiError>;
+  readonly downloadBlob: (
+    target: JmapMail.Target,
+    blobId: string,
+    options?: { name?: string; type?: string },
+  ) => Effect.Effect<Uint8Array, JmapApiError>;
+  readonly identityGet: (target: JmapMail.Target) => Effect.Effect<JmapMail.IdentityGetResult, JmapApiError>;
+  readonly emailSetUpdate: (
+    target: JmapMail.Target,
+    emailId: string,
+    patch: Record<string, unknown>,
+  ) => Effect.Effect<JmapMail.EmailSetResult, JmapApiError>;
+  readonly submitEmail: (
+    target: JmapMail.Target,
+    args: {
+      identityId: string;
+      draftsMailboxId: string;
+      sentMailboxId: string;
+      draft: {
+        from: readonly JmapMail.EmailAddress[];
+        to: readonly JmapMail.EmailAddress[];
+        cc?: readonly JmapMail.EmailAddress[];
+        bcc?: readonly JmapMail.EmailAddress[];
+        subject?: string;
+        inReplyTo?: readonly string[];
+        references?: readonly string[];
+        text: string;
+      };
+    },
+  ) => Effect.Effect<{ id: string; threadId: string | undefined }, JmapApiError>;
+}
+
+/**
+ * An in-memory JMAP dataset a {@link JmapMailApi.mock} serves — the session (account discovery), the
+ * folders (mailboxes), and the full emails the sync would fetch. Build one with `generateJmapDataset`
+ * from this plugin's `./testing`.
+ */
+export interface JmapDataset {
+  readonly session: Jmap.Session;
+  readonly folders: readonly JmapMail.Mailbox[];
+  /** Full emails, ordered ascending by `receivedAt` (the mock sorts/paginates a window over them). */
+  readonly emails: readonly JmapMail.Email[];
+  /** Attachment bytes keyed by `blobId`, served by `downloadBlob` for emails that carry one. */
+  readonly blobs?: Readonly<Record<string, Uint8Array>>;
+  /**
+   * Current `Email/get` state token — `emailGet` returns it and it's the newest `Email/changes` state.
+   * Set to exercise the incremental path; absent means "no delta support" (token capture returns undefined).
+   */
+  readonly state?: string;
+  /** Ordered `Email/changes` steps chaining `sinceState` → `newState`, each carrying the delta. */
+  readonly changeLog?: readonly JmapChangeStep[];
+}
+
+/** One `Email/changes` step in a {@link JmapDataset}'s change log. */
+export interface JmapChangeStep {
+  readonly sinceState: string;
+  readonly newState: string;
+  readonly created?: readonly string[];
+  readonly updated?: readonly string[];
+  readonly destroyed?: readonly string[];
+}
+
+/** Narrows an `unknown` filter value to a plain object so the mock can walk its conditions. */
+const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === 'object' && value !== null;
+
+/**
+ * Evaluates an `Email/query` filter against an email — enough of RFC 8621 §4.4.1 for the sync's
+ * generated filter: the `after`/`before` window, `inMailbox`/`inMailboxOtherThan` folder scope, and
+ * the AND/OR/NOT operator combinators. Unknown conditions are treated as matching.
+ */
+const matchesFilter = (email: JmapMail.Email, filter: unknown): boolean => {
+  if (!isRecord(filter)) {
+    return true;
+  }
+  if ('operator' in filter && Array.isArray(filter.conditions)) {
+    const results = filter.conditions.map((condition) => matchesFilter(email, condition));
+    if (filter.operator === 'OR') {
+      return results.some(Boolean);
+    }
+    if (filter.operator === 'NOT') {
+      return !results.some(Boolean);
+    }
+    return results.every(Boolean); // AND (the default the sync builds).
+  }
+
+  const receivedAt = new Date(email.receivedAt).getTime();
+  // `after` is inclusive (>=), `before` is exclusive (<) — matches the sync's window semantics.
+  if (typeof filter.after === 'string' && receivedAt < new Date(filter.after).getTime()) {
+    return false;
+  }
+  if (typeof filter.before === 'string' && receivedAt >= new Date(filter.before).getTime()) {
+    return false;
+  }
+  const mailboxIds = email.mailboxIds ? Object.keys(email.mailboxIds) : [];
+  if (typeof filter.inMailbox === 'string' && !mailboxIds.includes(filter.inMailbox)) {
+    return false;
+  }
+  if (Array.isArray(filter.inMailboxOtherThan)) {
+    const excluded = filter.inMailboxOtherThan;
+    if (!mailboxIds.some((id) => !excluded.includes(id))) {
+      return false;
+    }
+  }
+  return true;
+};
+
+/** Sorts emails by the query's primary sort (only `receivedAt` is used by the sync). */
+const sortEmails = (
+  emails: readonly JmapMail.Email[],
+  sort: readonly { property: string; isAscending?: boolean }[] | undefined,
+): readonly JmapMail.Email[] => {
+  const primary = sort?.[0];
+  if (!primary || primary.property !== 'receivedAt') {
+    return emails;
+  }
+  const direction = primary.isAscending ? 1 : -1;
+  return [...emails].sort(
+    (left, right) => direction * (new Date(left.receivedAt).getTime() - new Date(right.receivedAt).getTime()),
+  );
+};
+
+export class JmapMailApi extends Context.Tag('@dxos/plugin-inbox/JmapMailApi')<JmapMailApi, JmapMailApiService>() {
+  /**
+   * Live layer backed by the real JMAP HTTP client. Captures the auth/HTTP context once and provides
+   * it to each request, so the resulting service methods carry no requirements. Requires an
+   * `HttpClient` and a `JmapCredentials` (e.g. {@link JmapCredentials.fromConnection}) to be available
+   * where it is provided.
+   */
+  static readonly Live: Layer.Layer<JmapMailApi, never, Requirements> = Layer.effect(
+    JmapMailApi,
+    Effect.gen(function* () {
+      const context = yield* Effect.context<Requirements>();
+      return JmapMailApi.of({
+        getSession: Effect.provide(Jmap.getSession, context),
+        mailboxGet: (target) => Effect.provide(JmapMail.mailboxGet(target), context),
+        emailQuery: (target, options) => Effect.provide(JmapMail.emailQuery(target, options), context),
+        emailGet: (target, ids, properties) => Effect.provide(JmapMail.emailGet(target, ids, properties), context),
+        emailChanges: (target, sinceState, maxChanges) =>
+          Effect.provide(JmapMail.emailChanges(target, sinceState, maxChanges), context),
+        downloadBlob: (target, blobId, options) =>
+          Effect.provide(JmapMail.downloadBlob(target, blobId, options), context),
+        identityGet: (target) => Effect.provide(JmapMail.identityGet(target), context),
+        emailSetUpdate: (target, emailId, patch) =>
+          Effect.provide(JmapMail.emailSetUpdate(target, emailId, patch), context),
+        submitEmail: (target, args) => Effect.provide(JmapMail.submitEmail(target, args), context),
+      });
+    }),
+  );
+
+  /**
+   * Zero-dependency mock backed by an in-memory {@link JmapDataset} — for unit tests that drive the
+   * real sync pipeline with no live account. `emailQuery` honours the query filter (`after`/`before`
+   * window + folder scope), the `receivedAt` sort, and `position`/`limit` pagination, so the sync's
+   * window walk and pagination exercise realistically. Write methods are unsupported (die).
+   */
+  static readonly mock = (dataset: JmapDataset): Layer.Layer<JmapMailApi> => {
+    const byId = new Map(dataset.emails.map((email) => [email.id, email]));
+    return Layer.succeed(
+      JmapMailApi,
+      JmapMailApi.of({
+        getSession: Effect.succeed(dataset.session),
+        mailboxGet: () => Effect.succeed({ list: dataset.folders }),
+        emailQuery: (_target, options = {}) =>
+          Effect.sync(() => {
+            const matching = sortEmails(
+              dataset.emails.filter((email) => matchesFilter(email, options.filter)),
+              options.sort,
+            );
+            const position = options.position ?? 0;
+            const limit = options.limit ?? matching.length;
+            const page = matching.slice(position, position + limit);
+            return { position, total: matching.length, ids: page.map((email) => email.id) };
+          }),
+        emailGet: (_target, ids) =>
+          Effect.sync(() => ({
+            list: ids.map((id) => byId.get(id)).filter(Predicate.isNotNullable),
+            state: dataset.state,
+          })),
+        // Chains the change-log steps from `sinceState`, honoring `maxChanges`: it stops before a step
+        // that would exceed the budget (always including at least one, so a single oversized step still
+        // makes progress), sets `hasMoreChanges`, and returns the intermediate `newState` as the chunk
+        // boundary to resume from. An unknown/evicted state (no chain match, not already the latest) fails
+        // with `cannotCalculateChanges`, matching a server past its retention window.
+        emailChanges: (_target, sinceState, maxChanges) =>
+          Effect.gen(function* () {
+            const latest = dataset.state ?? sinceState;
+            if (sinceState === latest) {
+              return {
+                oldState: sinceState,
+                newState: latest,
+                hasMoreChanges: false,
+                created: [],
+                updated: [],
+                destroyed: [],
+              };
+            }
+            const created: string[] = [];
+            const updated: string[] = [];
+            const destroyed: string[] = [];
+            let chain = sinceState;
+            let matched = false;
+            let hasMoreChanges = false;
+            for (const step of dataset.changeLog ?? []) {
+              if (step.sinceState === chain) {
+                const stepSize =
+                  (step.created?.length ?? 0) + (step.updated?.length ?? 0) + (step.destroyed?.length ?? 0);
+                // Stop before overflowing the budget, but never before the first step (guarantees progress).
+                if (
+                  maxChanges !== undefined &&
+                  chain !== sinceState &&
+                  created.length + updated.length + destroyed.length + stepSize > maxChanges
+                ) {
+                  hasMoreChanges = true;
+                  break;
+                }
+                matched = true;
+                created.push(...(step.created ?? []));
+                updated.push(...(step.updated ?? []));
+                destroyed.push(...(step.destroyed ?? []));
+                chain = step.newState;
+              }
+            }
+            if (!matched) {
+              return yield* Effect.fail(
+                new JmapApiError(undefined, 'Cannot calculate changes', 'cannotCalculateChanges'),
+              );
+            }
+            return { oldState: sinceState, newState: chain, hasMoreChanges, created, updated, destroyed };
+          }),
+        downloadBlob: (_target, blobId) => {
+          const bytes = dataset.blobs?.[blobId];
+          return bytes
+            ? Effect.succeed(bytes)
+            : Effect.die(new Error(`mock JmapMailApi: blob not in dataset: ${blobId}`));
+        },
+        identityGet: () => Effect.die(new Error('mock JmapMailApi: identityGet not supported')),
+        emailSetUpdate: () => Effect.die(new Error('mock JmapMailApi: emailSetUpdate not supported')),
+        submitEmail: () => Effect.die(new Error('mock JmapMailApi: submitEmail not supported')),
+      }),
+    );
+  };
+}

package/src/testing/index.ts

@@ -0,0 +1,8 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './jmap-fixtures';
+export * from './sync-fixture';
+export type { JmapDataset } from '../services';
+export type { Jmap } from '../apis';

package/src/testing/jmap-fixtures.test.ts

@@ -0,0 +1,107 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import { describe, test } from 'vitest';
+
+import { EffectEx } from '@dxos/effect';
+
+import { type JmapMail } from '../apis';
+import { JmapMailApi } from '../services';
+import { generateJmapDataset } from './jmap-fixtures';
+
+const MAIL_ACCOUNT_CAPABILITY = 'urn:ietf:params:jmap:mail';
+const INBOX_ID = 'mb-inbox';
+
+describe('generateJmapDataset + JmapMailApi.mock', () => {
+  test('generates a coherent, ascending-by-date dataset', ({ expect }) => {
+    const { session, folders, emails } = generateJmapDataset({ count: 30, seed: 1 });
+    expect(session.primaryAccounts[MAIL_ACCOUNT_CAPABILITY]).toBeTruthy();
+    expect(folders.some((folder) => folder.role === 'inbox')).toBe(true);
+    expect(emails).toHaveLength(30);
+    // Every email has the sender + body the mapper reads.
+    for (const email of emails) {
+      expect(email.from?.[0]?.email).toMatch(/@/);
+      expect(email.subject).toBeTruthy();
+      const partId = email.textBody?.[0]?.partId;
+      expect(partId && email.bodyValues?.[partId]?.value).toBeTruthy();
+    }
+    // Ascending by receivedAt (the mock's window filter + sort rely on it).
+    const dates = emails.map((email) => new Date(email.receivedAt).getTime());
+    expect(dates).toEqual([...dates].sort((a, b) => a - b));
+  });
+
+  test('is deterministic for a fixed seed', ({ expect }) => {
+    // Pin the window too: with the default window anchored to `new Date()`, two calls a moment apart
+    // would produce different receivedAt values.
+    const window = { start: new Date('2026-01-01T00:00:00Z'), end: new Date('2026-02-01T00:00:00Z') };
+    const first = generateJmapDataset({ count: 10, seed: 7, ...window });
+    const second = generateJmapDataset({ count: 10, seed: 7, ...window });
+    expect(second.emails).toEqual(first.emails);
+  });
+
+  test('mock service discovers the session, folders, and paginates emails', async ({ expect }) => {
+    const dataset = generateJmapDataset({ count: 25, seed: 3 });
+    const accountId = dataset.session.primaryAccounts[MAIL_ACCOUNT_CAPABILITY];
+    const target: JmapMail.Target = { apiUrl: dataset.session.apiUrl, accountId };
+
+    const program = Effect.gen(function* () {
+      const api = yield* JmapMailApi;
+
+      const session = yield* api.getSession;
+      expect(session.apiUrl).toBe(dataset.session.apiUrl);
+
+      const { list: folders } = yield* api.mailboxGet(target);
+      expect(folders).toEqual(dataset.folders);
+
+      // Sorted newest-first; first page.
+      const sort = [{ property: 'receivedAt', isAscending: false }];
+      const page1 = yield* api.emailQuery(target, { sort, position: 0, limit: 10 });
+      expect(page1.ids).toHaveLength(10);
+      expect(page1.total).toBe(25);
+
+      // Walk the rest via position.
+      const page2 = yield* api.emailQuery(target, { sort, position: 10, limit: 10 });
+      const page3 = yield* api.emailQuery(target, { sort, position: 20, limit: 10 });
+      expect(page2.ids).toHaveLength(10);
+      expect(page3.ids).toHaveLength(5);
+
+      // No overlap; newest id first.
+      const all = [...page1.ids, ...page2.ids, ...page3.ids];
+      expect(new Set(all).size).toBe(25);
+
+      // emailGet resolves full bodies.
+      const { list } = yield* api.emailGet(target, [page1.ids[0]]);
+      expect(list[0]?.id).toBe(page1.ids[0]);
+      const partId = list[0]?.textBody?.[0]?.partId;
+      expect(partId && list[0]?.bodyValues?.[partId]?.value).toBeTruthy();
+    });
+
+    await EffectEx.runPromise(program.pipe(Effect.provide(JmapMailApi.mock(dataset))));
+  });
+
+  test('mock service honours the after/before window and folder scope', async ({ expect }) => {
+    const start = new Date('2026-01-01T00:00:00Z');
+    const end = new Date('2026-01-31T00:00:00Z');
+    const dataset = generateJmapDataset({ count: 30, seed: 5, start, end });
+    const accountId = dataset.session.primaryAccounts[MAIL_ACCOUNT_CAPABILITY];
+    const target: JmapMail.Target = { apiUrl: dataset.session.apiUrl, accountId };
+
+    const program = Effect.gen(function* () {
+      const api = yield* JmapMailApi;
+      // A window covering only the back half of the dataset, scoped to the inbox.
+      const { total } = yield* api.emailQuery(target, {
+        filter: { operator: 'AND', conditions: [{ after: '2026-01-16T00:00:00Z' }, { inMailbox: INBOX_ID }] },
+      });
+      expect(total).toBeGreaterThan(0);
+      expect(total).toBeLessThan(30);
+
+      // A folder with no emails yields nothing.
+      const empty = yield* api.emailQuery(target, { filter: { inMailbox: 'mb-sent' } });
+      expect(empty.total).toBe(0);
+    });
+
+    await EffectEx.runPromise(program.pipe(Effect.provide(JmapMailApi.mock(dataset))));
+  });
+});

package/src/testing/jmap-fixtures.ts

@@ -0,0 +1,105 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { subDays } from 'date-fns';
+
+import { random } from '@dxos/random';
+
+import { JmapMail } from '../apis';
+import { type JmapDataset } from '../services';
+
+export interface GenerateJmapDatasetOptions {
+  /** Number of emails to generate. */
+  count?: number;
+  /** Distinct conversation threads to spread emails across. Defaults to ~count/3. */
+  threads?: number;
+  /** Distinct senders. Defaults to ~count/5. */
+  senders?: number;
+  /** Custom (user) folder names, in addition to the always-present system folders. */
+  folders?: readonly string[];
+  /** Seed for deterministic output (same seed → same dataset). */
+  seed?: number;
+  /** `receivedAt` window. Defaults to [now − 90 days, now]. */
+  start?: Date;
+  end?: Date;
+  /** Prefix for email + thread ids, so disjoint datasets (e.g. date bands) don't collide. Defaults to `eml`. */
+  idPrefix?: string;
+}
+
+const MAIL_ACCOUNT_CAPABILITY = 'urn:ietf:params:jmap:mail';
+const ACCOUNT_ID = 'test-account';
+const INBOX_ID = 'mb-inbox';
+
+/** System folders every JMAP account has; the sync excludes trash/junk/drafts from the default scope. */
+const SYSTEM_FOLDERS: readonly JmapMail.Mailbox[] = [
+  { id: INBOX_ID, name: 'Inbox', role: 'inbox' },
+  { id: 'mb-sent', name: 'Sent', role: 'sent' },
+  { id: 'mb-drafts', name: 'Drafts', role: 'drafts' },
+  { id: 'mb-trash', name: 'Trash', role: 'trash' },
+  { id: 'mb-junk', name: 'Junk', role: 'junk' },
+];
+
+/** The session a {@link JmapMailApi.mock} serves — a single mail account discovered at `apiUrl`. */
+const SESSION = {
+  apiUrl: 'https://jmap.test/api/',
+  username: 'test@jmap.test',
+  primaryAccounts: { [MAIL_ACCOUNT_CAPABILITY]: ACCOUNT_ID },
+  downloadUrl: 'https://jmap.test/download/{accountId}/{blobId}/{name}?type={type}',
+};
+
+/**
+ * Deterministically generates a {@link JmapDataset} for driving {@link JmapMailApi.mock} in unit
+ * tests — no live account. Emails are ordered ascending by `receivedAt` and spread across the
+ * [start, end] window (all in the Inbox) so the sync's window walk + pagination exercise realistically.
+ * Mirrors `generateGmailDataset`.
+ */
+export const generateJmapDataset = (options: GenerateJmapDatasetOptions = {}): JmapDataset => {
+  const count = options.count ?? 100;
+  const threadCount = Math.max(1, options.threads ?? Math.ceil(count / 3));
+  const senderCount = Math.max(1, options.senders ?? Math.ceil(count / 5));
+  const end = options.end ?? new Date();
+  const start = options.start ?? subDays(end, 90);
+  const idPrefix = options.idPrefix ?? 'eml';
+  random.seed(options.seed ?? 42);
+
+  const customFolders: JmapMail.Mailbox[] = (options.folders ?? ['Work', 'Personal']).map((name, index) => ({
+    id: `mb-custom-${index + 1}`,
+    name,
+    role: null,
+  }));
+  const folders = [...SYSTEM_FOLDERS, ...customFolders];
+
+  const senders = Array.from({ length: senderCount }, () => ({
+    name: random.person.fullName(),
+    email: random.internet.email(),
+  }));
+  const threadIds = Array.from({ length: threadCount }, (_, index) => `${idPrefix}-thread-${index}`);
+
+  const startMs = start.getTime();
+  const endMs = end.getTime();
+
+  const emails: JmapMail.Email[] = Array.from({ length: count }, (_, index) => {
+    const sender = random.helpers.arrayElement(senders);
+    const threadId = random.helpers.arrayElement(threadIds);
+    // Monotonic ascending across the window (the mock relies on ascending receivedAt).
+    const receivedAtMs = Math.round(startMs + ((endMs - startMs) * index) / Math.max(1, count));
+    const subject = random.lorem.sentence();
+    const body = random.lorem.paragraph();
+
+    return {
+      id: `${idPrefix}-${index}`,
+      threadId,
+      mailboxIds: { [INBOX_ID]: true },
+      from: [{ name: sender.name, email: sender.email }],
+      to: [{ email: 'me@jmap.test' }],
+      subject,
+      receivedAt: new Date(receivedAtMs).toISOString(),
+      preview: body.slice(0, 100),
+      bodyValues: { body: { value: body } },
+      textBody: [{ partId: 'body', type: 'text/plain' }],
+    };
+  });
+
+  return { session: SESSION, folders, emails };
+};

package/src/testing/node.ts

@@ -0,0 +1,12 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// Deliberately does NOT re-export `./index` — that pulls `./sync-fixture`, which reaches
+// `@dxos/plugin-inbox/sync` and so `@dxos/compute` → `@dxos/ai`, whose parser uses `parsimmon`: a CJS
+// module Playwright's esbuild-based Node loader mishandles (`parsimmon.regexp is not a function`). The
+// same split, for the same reason, as `@dxos/plugin-inbox`'s `testing/node.ts`. Node consumers get the
+// deterministic fixtures plus the API contracts needed to build a faithful HTTP mock.
+export * from './jmap-fixtures';
+export type { JmapDataset } from '../services';
+export type { Jmap } from '../apis';