@dxos/plugin-jmap 0.10.0

package/src/apis/JmapMail/api.ts

@@ -0,0 +1,324 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as HttpClient from '@effect/platform/HttpClient';
+import * as HttpClientRequest from '@effect/platform/HttpClientRequest';
+import * as Effect from 'effect/Effect';
+
+import { withAuthorization } from '@dxos/compute-runtime';
+
+import { JmapApiError } from '../../errors';
+import { JmapCredentials } from '../../services/jmap-credentials';
+import {
+  MAIL_CAPABILITIES,
+  REQUEST_RETRY,
+  REQUEST_TIMEOUT,
+  SUBMISSION_CAPABILITIES,
+  getMethodResponse,
+  jmapRequest,
+  shouldRetry,
+} from '../Jmap/api';
+import {
+  type EmailAddress,
+  EmailChangesResult,
+  EmailGetResult,
+  EmailQueryResult,
+  EmailSetResult,
+  EmailSubmissionSetResult,
+  IdentityGetResult,
+  MailboxGetResult,
+} from './types';
+
+/**
+ * Resolved per-request context: the session `apiUrl`, the mail account id, and (optionally) the
+ * session's blob `downloadUrl` template (RFC 8620 §6.2). Most operations (mailboxGet, emailQuery,
+ * send, delete, …) don't need it and construct a `Target` without it; only the attachment-fetching
+ * path populates it from `Jmap.Session.downloadUrl`, so {@link downloadBlob} is the sole consumer
+ * that requires it — absent here just means "this call site never populated it", not "the server
+ * didn't advertise one" (every real session does).
+ */
+export type Target = {
+  readonly apiUrl: string;
+  readonly accountId: string;
+  readonly downloadUrl?: string;
+};
+
+/** Expands a JMAP `downloadUrl` URI Template (RFC 6570 level 1) with the given variables. */
+const expandDownloadUrl = (
+  template: string,
+  variables: { accountId: string; blobId: string; type: string; name: string },
+): string =>
+  template.replace(/\{(\w+)\}/g, (_, key: string) =>
+    key in variables ? encodeURIComponent(variables[key as keyof typeof variables]) : '',
+  );
+
+/**
+ * Downloads a blob's raw bytes via the session's `downloadUrl` template. `name`/`type` are advisory
+ * (they only affect the response's `Content-Disposition`/`Accept`), not required for correctness.
+ */
+export const downloadBlob = Effect.fn('downloadBlob')(function* (
+  target: Target,
+  blobId: string,
+  options: { name?: string; type?: string } = {},
+) {
+  if (!target.downloadUrl) {
+    return yield* Effect.fail(new JmapApiError(undefined, 'Session has no downloadUrl.'));
+  }
+  const url = expandDownloadUrl(target.downloadUrl, {
+    accountId: target.accountId,
+    blobId,
+    name: options.name ?? blobId,
+    type: options.type ?? 'application/octet-stream',
+  });
+
+  const { token } = yield* JmapCredentials;
+  const httpClient = yield* HttpClient.HttpClient.pipe(Effect.map(withAuthorization(token, 'Bearer')));
+
+  // Mapped to `JmapApiError` before `Effect.timeout`/`Effect.retry` so `shouldRetry` can actually
+  // distinguish a permanent 4xx from a transient failure — mirrors `jmapRequest`.
+  const buffer = yield* HttpClientRequest.get(url).pipe(
+    httpClient.execute,
+    Effect.flatMap((response) => response.arrayBuffer),
+    Effect.mapError(asJmapDownloadError),
+    Effect.timeout(REQUEST_TIMEOUT),
+    Effect.retry({ schedule: REQUEST_RETRY, while: shouldRetry }),
+    Effect.scoped,
+    Effect.mapError(asJmapDownloadError),
+  );
+  return new Uint8Array(buffer);
+});
+
+/** Collapses transport/decode failures into a typed {@link JmapApiError} (mirrors `Jmap/api.ts`). */
+const asJmapDownloadError = (error: unknown): JmapApiError =>
+  error instanceof JmapApiError
+    ? error
+    : new JmapApiError(undefined, error instanceof Error ? error.message : String(error));
+
+/** Email properties fetched by {@link emailGet} — enough for the mapper to build a Message. */
+export const EMAIL_PROPERTIES = [
+  'id',
+  'blobId',
+  'threadId',
+  'mailboxIds',
+  'keywords',
+  'from',
+  'to',
+  'cc',
+  'subject',
+  'receivedAt',
+  'sentAt',
+  'preview',
+  'messageId',
+  'inReplyTo',
+  'references',
+  'bodyValues',
+  'textBody',
+  'htmlBody',
+  'attachments',
+] as const;
+
+/** Lists all folders (mailboxes) in the account (RFC 8621 §2.3). */
+export const mailboxGet = Effect.fn('mailboxGet')(function* (target: Target) {
+  const response = yield* jmapRequest(target.apiUrl, {
+    using: MAIL_CAPABILITIES,
+    methodCalls: [['Mailbox/get', { accountId: target.accountId, ids: null }, '0']],
+  });
+  return yield* getMethodResponse(response, '0', MailboxGetResult);
+});
+
+/** Queries email ids matching a filter (RFC 8621 §4.4). */
+export const emailQuery = Effect.fn('emailQuery')(function* (
+  target: Target,
+  options: {
+    filter?: unknown;
+    sort?: readonly { property: string; isAscending?: boolean }[];
+    position?: number;
+    limit?: number;
+    calculateTotal?: boolean;
+  } = {},
+) {
+  const args: Record<string, unknown> = { accountId: target.accountId };
+  if (options.filter !== undefined) {
+    args.filter = options.filter;
+  }
+  if (options.sort !== undefined) {
+    args.sort = options.sort;
+  }
+  if (options.position !== undefined) {
+    args.position = options.position;
+  }
+  if (options.limit !== undefined) {
+    args.limit = options.limit;
+  }
+  if (options.calculateTotal !== undefined) {
+    args.calculateTotal = options.calculateTotal;
+  }
+
+  const response = yield* jmapRequest(target.apiUrl, {
+    using: MAIL_CAPABILITIES,
+    methodCalls: [['Email/query', args, '0']],
+  });
+  return yield* getMethodResponse(response, '0', EmailQueryResult);
+});
+
+/** Fetches emails by id with decoded HTML and text body values (RFC 8621 §4.2). */
+export const emailGet = Effect.fn('emailGet')(function* (
+  target: Target,
+  ids: readonly string[],
+  properties: readonly string[] = EMAIL_PROPERTIES,
+) {
+  const response = yield* jmapRequest(target.apiUrl, {
+    using: MAIL_CAPABILITIES,
+    methodCalls: [
+      [
+        'Email/get',
+        { accountId: target.accountId, ids, properties, fetchTextBodyValues: true, fetchHTMLBodyValues: true },
+        '0',
+      ],
+    ],
+  });
+  return yield* getMethodResponse(response, '0', EmailGetResult);
+});
+
+/**
+ * Fetches the delta of email changes since an opaque `sinceState` token (RFC 8621 §4.3). A server that
+ * can't compute the delta (state too old / evicted) returns a `cannotCalculateChanges` method error,
+ * surfaced as a {@link JmapApiError} with that `type` — the caller's cue to fall back to a full scan.
+ * The token to pass comes from a prior `Email/get` `state` (NOT `Email/query` `queryState`).
+ */
+export const emailChanges = Effect.fn('emailChanges')(function* (
+  target: Target,
+  sinceState: string,
+  maxChanges?: number,
+) {
+  const args: Record<string, unknown> = { accountId: target.accountId, sinceState };
+  if (maxChanges !== undefined) {
+    args.maxChanges = maxChanges;
+  }
+  const response = yield* jmapRequest(target.apiUrl, {
+    using: MAIL_CAPABILITIES,
+    methodCalls: [['Email/changes', args, '0']],
+  });
+  return yield* getMethodResponse(response, '0', EmailChangesResult);
+});
+
+/** Lists the account's sending identities (RFC 8621 §6.2). */
+export const identityGet = Effect.fn('identityGet')(function* (target: Target) {
+  const response = yield* jmapRequest(target.apiUrl, {
+    using: SUBMISSION_CAPABILITIES,
+    methodCalls: [['Identity/get', { accountId: target.accountId, ids: null }, '0']],
+  });
+  return yield* getMethodResponse(response, '0', IdentityGetResult);
+});
+
+/** Patches a single email (e.g. replace `mailboxIds` to move to Trash). Idempotent, so retryable. */
+export const emailSetUpdate = Effect.fn('emailSetUpdate')(function* (
+  target: Target,
+  emailId: string,
+  patch: Record<string, unknown>,
+) {
+  const response = yield* jmapRequest(target.apiUrl, {
+    using: MAIL_CAPABILITIES,
+    methodCalls: [['Email/set', { accountId: target.accountId, update: { [emailId]: patch } }, '0']],
+  });
+  const result = yield* getMethodResponse(response, '0', EmailSetResult);
+  const error = result.notUpdated?.[emailId];
+  if (error) {
+    return yield* Effect.fail(new JmapApiError(undefined, error.description ?? error.type, error.type));
+  }
+  return result;
+});
+
+/**
+ * Creates a draft and submits it for delivery in a single batched request. Not retried (a retry
+ * could double-send). Returns the created email's id and thread id.
+ */
+export const submitEmail = Effect.fn('submitEmail')(function* (
+  target: Target,
+  args: {
+    identityId: string;
+    draftsMailboxId: string;
+    sentMailboxId: string;
+    draft: {
+      from: readonly EmailAddress[];
+      to: readonly EmailAddress[];
+      cc?: readonly EmailAddress[];
+      bcc?: readonly EmailAddress[];
+      subject?: string;
+      inReplyTo?: readonly string[];
+      references?: readonly string[];
+      text: string;
+    };
+  },
+) {
+  const { identityId, draftsMailboxId, sentMailboxId, draft } = args;
+  const draftCreate: Record<string, unknown> = {
+    mailboxIds: { [draftsMailboxId]: true },
+    keywords: { $draft: true, $seen: true },
+    from: draft.from,
+    to: draft.to,
+    bodyValues: { body: { value: draft.text } },
+    textBody: [{ partId: 'body', type: 'text/plain' }],
+  };
+  if (draft.cc && draft.cc.length > 0) {
+    draftCreate.cc = draft.cc;
+  }
+  if (draft.bcc && draft.bcc.length > 0) {
+    draftCreate.bcc = draft.bcc;
+  }
+  if (draft.subject !== undefined) {
+    draftCreate.subject = draft.subject;
+  }
+  if (draft.inReplyTo && draft.inReplyTo.length > 0) {
+    draftCreate.inReplyTo = draft.inReplyTo;
+  }
+  if (draft.references && draft.references.length > 0) {
+    draftCreate.references = draft.references;
+  }
+
+  const response = yield* jmapRequest(
+    target.apiUrl,
+    {
+      using: SUBMISSION_CAPABILITIES,
+      methodCalls: [
+        ['Email/set', { accountId: target.accountId, create: { draft: draftCreate } }, '0'],
+        [
+          'EmailSubmission/set',
+          {
+            accountId: target.accountId,
+            create: { sub: { emailId: '#draft', identityId } },
+            onSuccessUpdateEmail: {
+              '#sub': {
+                [`mailboxIds/${draftsMailboxId}`]: null,
+                [`mailboxIds/${sentMailboxId}`]: true,
+                'keywords/$draft': null,
+              },
+            },
+          },
+          '1',
+        ],
+      ],
+    },
+    { retry: false },
+  );
+
+  const setResult = yield* getMethodResponse(response, '0', EmailSetResult);
+  const created = setResult.created?.draft;
+  if (!created) {
+    const error = setResult.notCreated?.draft;
+    return yield* Effect.fail(
+      new JmapApiError(undefined, error?.description ?? error?.type ?? 'Draft was not created.', error?.type),
+    );
+  }
+
+  const submissionResult = yield* getMethodResponse(response, '1', EmailSubmissionSetResult);
+  if (!submissionResult.created?.sub) {
+    const error = submissionResult.notCreated?.sub;
+    return yield* Effect.fail(
+      new JmapApiError(undefined, error?.description ?? error?.type ?? 'Email submission failed.', error?.type),
+    );
+  }
+
+  return { id: created.id, threadId: created.threadId };
+});

package/src/apis/JmapMail/index.ts

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

package/src/apis/JmapMail/query.test.ts

@@ -0,0 +1,181 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { subDays, subMonths, subWeeks, subYears } from 'date-fns';
+import * as Option from 'effect/Option';
+import { describe, test } from 'vitest';
+
+import { type Filter } from '../Jmap';
+import { filterScopesMailbox, parseMailQuery, resolveMailboxByNameOrRole } from './query';
+import { type Mailbox } from './types';
+
+const FOLDERS: Mailbox[] = [
+  { id: 'mb-inbox', name: 'Inbox', role: 'inbox' },
+  { id: 'mb-sent', name: 'Sent', role: 'sent' },
+  { id: 'mb-junk', name: 'Spam', role: 'junk' },
+  { id: 'mb-school', name: 'School', role: null },
+];
+
+const NOW = new Date('2026-06-15T00:00:00.000Z');
+
+const ctx = { now: NOW, resolveMailbox: (nameOrRole: string) => resolveMailboxByNameOrRole(FOLDERS, nameOrRole) };
+
+// Returns the parsed filter, or `null` when the query yields no filter.
+const parse = (query: string): Filter | null => Option.getOrNull(parseMailQuery(query, ctx));
+
+describe('parseMailQuery', () => {
+  test('empty / whitespace yields no filter', ({ expect }) => {
+    expect(parse('')).toBeNull();
+    expect(parse('   ')).toBeNull();
+  });
+
+  test('bare words become full-text conditions, AND-ed', ({ expect }) => {
+    expect(parse('hello')).toEqual({ text: 'hello' });
+    expect(parse('hello world')).toEqual({ operator: 'AND', conditions: [{ text: 'hello' }, { text: 'world' }] });
+  });
+
+  test('quoted phrases stay intact', ({ expect }) => {
+    expect(parse('"hello world"')).toEqual({ text: 'hello world' });
+    expect(parse('subject:"hello world"')).toEqual({ subject: 'hello world' });
+  });
+
+  test('address and subject/body operators', ({ expect }) => {
+    expect(parse('from:alice@x.com')).toEqual({ from: 'alice@x.com' });
+    expect(parse('to:bob@x.com')).toEqual({ to: 'bob@x.com' });
+    expect(parse('cc:carol@x.com')).toEqual({ cc: 'carol@x.com' });
+    expect(parse('bcc:dan@x.com')).toEqual({ bcc: 'dan@x.com' });
+    expect(parse('subject:invoice')).toEqual({ subject: 'invoice' });
+    expect(parse('body:receipt')).toEqual({ body: 'receipt' });
+  });
+
+  test('label / in resolve to a mailbox id (by name or role/alias)', ({ expect }) => {
+    expect(parse('label:School')).toEqual({ inMailbox: 'mb-school' });
+    expect(parse('label:school')).toEqual({ inMailbox: 'mb-school' });
+    expect(parse('in:inbox')).toEqual({ inMailbox: 'mb-inbox' });
+    expect(parse('in:spam')).toEqual({ inMailbox: 'mb-junk' });
+  });
+
+  test('an unknown label drops the term (and yields no filter when alone)', ({ expect }) => {
+    expect(parse('label:Nonexistent')).toBeNull();
+    expect(parse('label:Nonexistent subject:hi')).toEqual({ subject: 'hi' });
+  });
+
+  test('is: maps to keyword conditions', ({ expect }) => {
+    expect(parse('is:unread')).toEqual({ notKeyword: '$seen' });
+    expect(parse('is:read')).toEqual({ hasKeyword: '$seen' });
+    expect(parse('is:starred')).toEqual({ hasKeyword: '$flagged' });
+    expect(parse('is:draft')).toEqual({ hasKeyword: '$draft' });
+    expect(parse('is:bogus')).toBeNull();
+  });
+
+  test('has:attachment', ({ expect }) => {
+    expect(parse('has:attachment')).toEqual({ hasAttachment: true });
+    expect(parse('has:nope')).toBeNull();
+  });
+
+  test('absolute dates (slash or dash) become UTC before/after', ({ expect }) => {
+    expect(parse('after:2024/01/01')).toEqual({ after: '2024-01-01T00:00:00.000Z' });
+    expect(parse('before:2024-12-31')).toEqual({ before: '2024-12-31T00:00:00.000Z' });
+    expect(parse('newer:2024/06/01')).toEqual({ after: '2024-06-01T00:00:00.000Z' });
+    expect(parse('after:not-a-date')).toBeNull();
+  });
+
+  test('relative dates compute from `now`', ({ expect }) => {
+    expect(parse('newer_than:7d')).toEqual({ after: subDays(NOW, 7).toISOString() });
+    expect(parse('newer_than:2w')).toEqual({ after: subWeeks(NOW, 2).toISOString() });
+    expect(parse('older_than:3m')).toEqual({ before: subMonths(NOW, 3).toISOString() });
+    expect(parse('older_than:1y')).toEqual({ before: subYears(NOW, 1).toISOString() });
+  });
+
+  test('size operators parse units', ({ expect }) => {
+    expect(parse('larger:10M')).toEqual({ minSize: 10 * 1024 * 1024 });
+    expect(parse('smaller:500k')).toEqual({ maxSize: 500 * 1024 });
+    expect(parse('larger:2048')).toEqual({ minSize: 2048 });
+  });
+
+  test('list / deliveredto map to header conditions', ({ expect }) => {
+    expect(parse('list:dev.example.com')).toEqual({ header: ['List-Id', 'dev.example.com'] });
+    expect(parse('deliveredto:me@x.com')).toEqual({ header: ['Delivered-To', 'me@x.com'] });
+  });
+
+  test('negation wraps a term in NOT', ({ expect }) => {
+    expect(parse('-from:noreply@x.com')).toEqual({ operator: 'NOT', conditions: [{ from: 'noreply@x.com' }] });
+  });
+
+  test('OR groups adjacent terms', ({ expect }) => {
+    expect(parse('from:a@x.com OR from:b@x.com')).toEqual({
+      operator: 'OR',
+      conditions: [{ from: 'a@x.com' }, { from: 'b@x.com' }],
+    });
+  });
+
+  test('consecutive ORs flatten into a single OR', ({ expect }) => {
+    expect(parse('a OR b OR c')).toEqual({
+      operator: 'OR',
+      conditions: [{ text: 'a' }, { text: 'b' }, { text: 'c' }],
+    });
+  });
+
+  test('OR binds tighter than the implicit AND chain', ({ expect }) => {
+    expect(parse('from:a OR from:b subject:c')).toEqual({
+      operator: 'AND',
+      conditions: [{ operator: 'OR', conditions: [{ from: 'a' }, { from: 'b' }] }, { subject: 'c' }],
+    });
+  });
+
+  test('a dropped term consumes the pending OR (next term is AND, not OR)', ({ expect }) => {
+    // `label:Unknown` drops out; `subject:c` must NOT OR-merge with `from:a`.
+    expect(parse('from:a OR label:Unknown subject:c')).toEqual({
+      operator: 'AND',
+      conditions: [{ from: 'a' }, { subject: 'c' }],
+    });
+  });
+
+  test('a realistic combined query', ({ expect }) => {
+    expect(parse('label:School is:unread newer_than:14d -from:noreply@x.com')).toEqual({
+      operator: 'AND',
+      conditions: [
+        { inMailbox: 'mb-school' },
+        { notKeyword: '$seen' },
+        { after: subDays(NOW, 14).toISOString() },
+        { operator: 'NOT', conditions: [{ from: 'noreply@x.com' }] },
+      ],
+    });
+  });
+
+  test('an unknown operator falls back to a literal full-text term', ({ expect }) => {
+    expect(parse('foo:bar')).toEqual({ text: 'foo:bar' });
+  });
+});
+
+describe('resolveMailboxByNameOrRole', () => {
+  test('resolves by case-insensitive name', ({ expect }) => {
+    expect(Option.getOrNull(resolveMailboxByNameOrRole(FOLDERS, 'school'))).toBe('mb-school');
+    expect(Option.getOrNull(resolveMailboxByNameOrRole(FOLDERS, 'SCHOOL'))).toBe('mb-school');
+  });
+
+  test('resolves by role and alias', ({ expect }) => {
+    expect(Option.getOrNull(resolveMailboxByNameOrRole(FOLDERS, 'inbox'))).toBe('mb-inbox');
+    expect(Option.getOrNull(resolveMailboxByNameOrRole(FOLDERS, 'spam'))).toBe('mb-junk');
+  });
+
+  test('returns None for an unknown name', ({ expect }) => {
+    expect(Option.getOrNull(resolveMailboxByNameOrRole(FOLDERS, 'nope'))).toBeNull();
+  });
+});
+
+describe('filterScopesMailbox', () => {
+  test('true when any condition restricts the mailbox', ({ expect }) => {
+    expect(filterScopesMailbox({ inMailbox: 'mb-school' })).toBe(true);
+    expect(filterScopesMailbox({ inMailboxOtherThan: ['mb-junk'] })).toBe(true);
+    expect(filterScopesMailbox({ operator: 'AND', conditions: [{ from: 'a' }, { inMailbox: 'x' }] })).toBe(true);
+  });
+
+  test('false when no condition restricts the mailbox', ({ expect }) => {
+    expect(filterScopesMailbox({ from: 'a@x.com' })).toBe(false);
+    expect(filterScopesMailbox({ operator: 'OR', conditions: [{ notKeyword: '$seen' }, { subject: 'x' }] })).toBe(
+      false,
+    );
+  });
+});