json-meta-client

[!WARNING] This library is alpha software.

Overview

A JMAP client compatible with Node.js and the browser.

Installation

pnpm add json-meta-client

Usage

Create a client with the capabilities your JMAP server supports:

import { Client } from "json-meta-client";
import {
  mail,
  submission,
  contacts,
} from "json-meta-client/capabilities";

const client = new Client({
  bearerToken: "<token>",
  sessionUrl: "<session-url>",
  capabilities: [mail, submission, contacts], // `core` is always included
});

Issue a single JMAP request

const response = await client.api.Mailbox.query({
  filter: { role: "inbox" },
  limit: 1,
});

const [inboxId] = response.ids;

{
  "using": [
    "urn:ietf:params:jmap:core",
    "urn:ietf:params:jmap:mail"
  ],
  "methodCalls": [
    [
      "Mailbox/query",
      {
        "accountId": "<primary-account-id>",
        "filter": { "role": "inbox" },
        "limit": 1
      },
      "<opaque id>"
    ]
  ]
}

Issue a batch of JMAP requests

This takes advantage of result references[^1]

import { ref } from "json-meta-client";

// Note the lack of `await` here:
const emailsQuery = client.api.Email.query({
  inMailbox: inboxId,
  limit: 10,
});

const emails = await client.api.Email.get({
  ids: ref(emailsQuery, "/ids"),
});

{
  "using": [
    "urn:ietf:params:jmap:core",
    "urn:ietf:params:jmap:mail"
  ],
  "methodCalls": [
    [
      "Email/query",
      {
        "accountId": "<primary-account-id>",
        "inMailbox": "<inbox-id>",
        "limit": 10
      },
      "<opaque id #1>"
    ],
    [
      "Email/get",
      {
        "accountId": "<primary-account-id>",
        "#ids": {
          "name": "Email/query",
          "resultOf": "<opaque id #1>",
          "path": "/ids"
        }
      },
      "<opaque id #2>"
    ]
  ]
}

Architecture

Proxies for Method Calls

TODO: Discuss the use of a Proxy for determining method calls

Deferred Request Batching

TODO: Discuss the use of batcher for grouping requests via promise mechanics

[^1]: RFC 8620 § 3.7 - References to Previous Method Results