README.md

jmap-yacl

Another lightweight client library for working with the JMAP, which supports working with JavaScript, TypeScript, and also has built-in types for Typebox.

Installation

Bun install:

bun add jmap-yacl

NPM install:

npm install jmap-yacl

Information

The library was developed and tested using stalwart mail-server, work with other JMAP servers is not guaranteed (but in theory it should be due to RFC compliance). Only basic authentication (username + password) is supported.

Implemented:

• JMAP standard according to RFC 8620 (without Push)
• JMAP Mail standard according to RFC 8621

Inspiration:

• stalwartlabs/jmap-client
• htunnicliff/jmap-jam

Compliance with standards:

• RFC 8620 - The JSON Meta Application Protocol (JMAP)
• RFC 8621 - The JSON Meta Application Protocol (JMAP) for Mail
• RFC 7807 - Problem Details in HTTP APIs

Getting started

To start working with the API, you need to create a JMAP Client and authorize it. This can be done using a few lines below:

const client = new JMAPClient({
  username: process.env.JMAP_USERNAME,
  password: process.env.JMAP_PASSWORD,
});

await client.connect("https://YOURDOMAIN/.well-known/jmap");

In order to make a request to JMAP, you can use two types of requests::

1. Ready-made methods for simple single requests to the server
2. Raw requests, if you want to make a complex request to the server

  const client = ...

  // ready methods
  const identityResponse = await client.identity.get({
    accountId: "abc",
  });

  // raw requests
  const identityResponse = await client.request<
    JMAP.GetResponse<JMAPMail.Identity[]>
  >("/jmap", {
    using: [JMAP.Using.mail],
    invocation: [
      "Identity/get",
      {
        accountId: "abc",
      },
      "a",
    ],
  });

Building

1. Install Bun

2. Install dependencies:

bun install

3. Run the build:

   3.0. Full build:

   bun build:bun

   3.1. If you want to build only typescript types:

   bun build:declaration

   3.2. If you want to build only type box types:

   bun build:typebox

4. Install the pre-commit hook:

   bun prepare

Tests

The library has minimal test coverage to check its performance.

Run the tests:

bun test