@push.rocks/smartjmap 1.0.0 → 2.0.0

package/readme.md

@@ -1,6 +1,6 @@
 # @push.rocks/smartjmap
 
-A TypeScript JMAP client for reading, sending, and watching mail via the JSON Meta Application Protocol (RFC 8620/8621), with a bundled test server for offline testing.
+A TypeScript JMAP toolkit (RFC 8620/8621): an event-driven mail client for reading, sending, and watching mail, plus an embeddable JMAP server core with pluggable storage for exposing your own mail store to JMAP clients.
 
 ## Install
 
@@ -10,11 +10,14 @@ To install `@push.rocks/smartjmap`, use pnpm (or npm):
 pnpm install @push.rocks/smartjmap
 ```
 
-The package has zero runtime dependencies — it uses the global `fetch` available in Node.js 18+.
+The package has zero runtime dependencies — it uses the global `fetch`, `Request`/`Response`, and `ReadableStream` available in Node.js 18+ (and in Deno/Bun for the server core).
 
 ## Usage
 
-`@push.rocks/smartjmap` connects to any JMAP server (Fastmail, Stalwart, Cyrus, ...), watches a mailbox for new mail in an event-driven way, and exposes the common mail operations: querying, reading, flagging, sending, and blob downloads.
+`@push.rocks/smartjmap` ships two sides of the protocol:
+
+- `JmapClient` connects to any JMAP server (Fastmail, Stalwart, Cyrus, ...), watches a mailbox for new mail in an event-driven way, and exposes the common mail operations: querying, reading, flagging, sending, uploads, and blob downloads.
+- `JmapServer` is a JMAP server core: it implements the RFC 8620 request layer and the RFC 8621 mail method surface, and dispatches all storage into a pluggable `IJmapMailBackend`. With no options it runs on a bundled in-memory backend, which makes it an offline test server; with your own backend it exposes a real mail store to JMAP clients.
 
 ### Importing the Required Modules
 
@@ -24,7 +27,7 @@ import { JmapClient, type IJmapClientConfig } from '@push.rocks/smartjmap';
 
 ### Configuration Object
 
-Point the client at the JMAP session resource — most servers expose it at the autodiscovery path `https://host/.well-known/jmap`. All URLs inside the session (API endpoint, download URL, event source) are resolved relative to this URL automatically.
+Point the client at the JMAP session resource — most servers expose it at the autodiscovery path `https://host/.well-known/jmap`. All URLs inside the session (API endpoint, upload/download URLs, event source) are resolved relative to this URL automatically.
 
 ```typescript
 const jmapConfig: IJmapClientConfig = {
@@ -161,6 +164,25 @@ console.log(result.emailId, result.submissionId);
 
 When `from` is omitted, the first identity of the account is used.
 
+### Uploads and Attachments
+
+`uploadBlob` POSTs raw bytes to the session's upload URL (RFC 8620 §6.1) and returns the stored blob's id, type, and size. Reference the blob id in `sendEmail` to attach it:
+
+```typescript
+const upload = await jmapClient.uploadBlob(
+  new TextEncoder().encode('quarterly report data'),
+  'text/plain'
+);
+console.log(upload.blobId, upload.size);
+
+await jmapClient.sendEmail({
+  to: [{ email: 'friend@example.com' }],
+  subject: 'Report attached',
+  textBody: 'Please find the report attached.',
+  attachments: [{ blobId: upload.blobId, type: 'text/plain', name: 'report.txt' }],
+});
+```
+
 ### Downloading Blobs
 
 Raw messages and attachments are blobs; download them via the session's download URL template:
@@ -194,25 +216,30 @@ await jmapClient.disconnect();
 
 `disconnect()` tears down the event stream and any polling timer — no handles are left open — and emits `disconnected`.
 
-### The Bundled Test Server
+## Running a JMAP server
+
+`JmapServer` handles the protocol; storage is behind the `IJmapMailBackend` interface. Endpoints served: the session resource (`/.well-known/jmap` and `/jmap/session`), the API (`/jmap/api`), uploads (`/jmap/upload/{accountId}`), downloads (`/jmap/download/{accountId}/{blobId}/{name}?type=`), and StateChange pushes via SSE (`/jmap/eventsource`, RFC 8620 §7.3 with `types`, `closeafter=state`, and `ping` keepalive support).
+
+### The Offline Test Server
 
-`JmapServer` is a minimal in-memory JMAP server for offline tests. It serves the session resource at `/.well-known/jmap` (and `/jmap/session`), the API at `/jmap/api`, blob downloads, and StateChange pushes via SSE at `/jmap/eventsource`. It validates Bearer and Basic auth and answers unauthenticated requests with `401` + `WWW-Authenticate`.
+With no options, `JmapServer` uses a fresh `MemoryMailBackend` plus a static credential registry — an offline JMAP server for tests. Seed users on the server (auth) and mail on the backend (storage):
 
 ```typescript
-import { JmapClient, JmapServer } from '@push.rocks/smartjmap';
+import { JmapClient, JmapServer, MemoryMailBackend } from '@push.rocks/smartjmap';
 
-const jmapServer = new JmapServer();
+const backend = new MemoryMailBackend();
+const jmapServer = new JmapServer({ backend });
 jmapServer.addUser('testuser', 'testpass');
 jmapServer.addBearerToken('testuser', 'test-token');
-jmapServer.createMailbox('testuser', 'INBOX', 'inbox');
-jmapServer.addEmail('testuser', 'INBOX', {
+backend.createMailbox('testuser', 'INBOX', 'inbox');
+backend.addEmail('testuser', 'INBOX', {
   from: { email: 'alice@example.com' },
   to: { email: 'testuser@example.com' },
   subject: 'Welcome',
   textBody: 'Hello from the test server!',
 });
 
-const port = await jmapServer.start(0); // resolves with the bound port
+const port = await jmapServer.start(0); // node:http wrapper; resolves with the bound port
 
 const client = new JmapClient({
   sessionUrl: `http://127.0.0.1:${port}/.well-known/jmap`,
@@ -221,8 +248,9 @@ const client = new JmapClient({
 client.on('message', (message) => console.log(message.subject));
 await client.connect();
 
-// Emails added while a client is connected are pushed via SSE:
-jmapServer.addEmail('testuser', 'INBOX', {
+// Backend mutations outside a JMAP request (e.g. seeding, an IMAP bridge)
+// flow through the change feed and are pushed to clients via SSE:
+backend.addEmail('testuser', 'INBOX', {
   from: { email: 'bob@example.com' },
   to: { email: 'testuser@example.com' },
   subject: 'Live push',
@@ -230,12 +258,84 @@ jmapServer.addEmail('testuser', 'INBOX', {
 });
 
 await client.disconnect();
-await jmapServer.stop(); // closes the server and destroys open connections
+await jmapServer.stop(); // closes event streams, timers, and open connections
 ```
 
-The dispatched methods are `Core/echo`, `Mailbox/get`, `Mailbox/query`, `Email/get`, `Email/query`, `Email/changes`, `Email/set`, `Identity/get`, and `EmailSubmission/set` — enough for every public `JmapClient` method to run offline.
+### Mounting fetchHandler (Deno, Bun, anywhere)
+
+`fetchHandler(request: Request): Promise<Response>` is the primary API and handles every endpoint, including the SSE event source (served as a `ReadableStream` response). `start(port)` is only a node:http adapter around it. In a Deno app:
+
+```typescript
+// deno run --allow-net server.ts
+import { JmapServer, MemoryMailBackend } from '@push.rocks/smartjmap';
+
+const backend = new MemoryMailBackend();
+const jmapServer = new JmapServer({ backend, baseUrl: 'http://localhost:8080' });
+jmapServer.addUser('demo', 'demopass');
+backend.createMailbox('demo', 'INBOX', 'inbox');
+
+Deno.serve({ port: 8080 }, (request) => jmapServer.fetchHandler(request));
+```
+
+`baseUrl` makes the URLs advertised in the session object absolute; without it they are relative and JMAP clients resolve them against the session URL.
+
+### Custom Authentication
+
+The `authenticate` option replaces the built-in Basic/Bearer registry entirely. It receives the raw `Request` and returns a principal (or null for 401); the backend then maps the principal to an account via `resolveAccount`:
+
+```typescript
+import { JmapServer } from '@push.rocks/smartjmap';
+
+const jmapServer = new JmapServer({
+  authenticate: async (request: Request) => {
+    const token = request.headers.get('x-app-token');
+    return token === 'sesame' ? { username: 'appuser' } : null;
+  },
+});
+```
+
+### Implementing a Real Backend
+
+Implement `IJmapMailBackend` against your own store to serve real mail. All state strings are backend-owned opaque strings. The contract (all methods async except `subscribeToChanges`, which returns its unsubscribe function synchronously):
+
+| Method | Serves |
+| --- | --- |
+| `resolveAccount(principal)` | principal → account mapping for the session |
+| `getMailboxes(accountId, ids)` / `getMailboxChanges(accountId, sinceState, maxChanges?)` | `Mailbox/get`, `Mailbox/query`, `Mailbox/changes` |
+| `getEmails(accountId, ids, properties?)` | `Email/get` (the server applies projection and body-value fetch flags) |
+| `queryEmails(accountId, options)` | `Email/query` (filter subset, receivedAt sort, position/limit/total) |
+| `getEmailChanges(accountId, sinceState, maxChanges?)` | `Email/changes` (return null for `cannotCalculateChanges`) |
+| `setEmails(accountId, request)` | `Email/set` (creates, normalized keyword/mailbox updates, destroys) |
+| `getThreads(accountId, ids)` | `Thread/get` |
+| `uploadBlob(accountId, data, type)` / `getBlob(accountId, blobId)` | upload/download endpoints and raw-message access |
+| `getIdentities(accountId)` | `Identity/get` |
+| `submitEmail(accountId, submission)` | `EmailSubmission/set` — receives the resolved envelope plus the raw RFC 5322 payload; your backend performs the actual sending |
+| `subscribeToChanges(listener)` | StateChange pushes — the server's only push feed, so notify on all mutations, including those made through JMAP requests, not just out-of-band changes |
+
+```typescript
+import { JmapServer, type IJmapMailBackend } from '@push.rocks/smartjmap';
+
+declare const myBackend: IJmapMailBackend; // your implementation
+
+const jmapServer = new JmapServer({
+  backend: myBackend,
+  baseUrl: 'https://mail.example.com',
+});
+```
+
+`MemoryMailBackend` is the reference implementation — a readable starting point for the expected semantics.
+
+### What the Server Advertises (and What It Doesn't)
+
+The session object advertises `urn:ietf:params:jmap:core`, `urn:ietf:params:jmap:mail`, and `urn:ietf:params:jmap:submission`. The core limits are enforced, not just advertised (exported as `JMAP_SERVER_LIMITS`): `maxSizeRequest` 10 MB, `maxCallsInRequest` 16, `maxObjectsInGet`/`maxObjectsInSet` 500, `maxSizeUpload` 50 MB, and `maxConcurrentRequests` 4 — violations produce request-level `limit` errors or `requestTooLarge` method errors. `maxDelayedSend` is 0 (no delayed send) and `mayCreateTopLevelMailbox` is false (no `Mailbox/set`).
+
+The request layer implements `using` validation (`unknownCapability`), `#`-prefixed back-references with full `ResultReference` `{ resultOf, name, path }` JSON-pointer resolution including `/*` array expansion, client-provided `createdIds` maps, and `unknownMethod`/`invalidArguments`/`serverFail` error responses.
+
+Dispatched methods: `Core/echo`, `Mailbox/get`, `Mailbox/query`, `Mailbox/changes`, `Thread/get`, `Email/get` (property projection, `fetchTextBodyValues`/`fetchHTMLBodyValues`/`fetchAllBodyValues`, `maxBodyValueBytes` truncation), `Email/query` (filters: `inMailbox`, `text`, `subject`, `from`, `to`, `before`, `after`, `hasKeyword`, `notKeyword`; `receivedAt` sort; `position`/`limit`/`calculateTotal`), `Email/changes`, `Email/set` (create/update/destroy with RFC 8620 §5.3 JSON-pointer patches for `keywords/*` and `mailboxIds/*`, plus `ifInState`), `Identity/get`, and `EmailSubmission/set` (with `onSuccessUpdateEmail`/`onSuccessDestroyEmail` and the implicit `Email/set` response).
+
+Not implemented in this phase: `Email/queryChanges` (answered with an explicit `cannotCalculateChanges` error), `Mailbox/set`, `Email/copy`/`Email/import`/`Email/parse`, `SearchSnippet/*`, `VacationResponse/*`, `PushSubscription` (RFC 8620 §7.2 — the §7.3 event source is the push channel), `FilterOperator` trees (`AND`/`OR`/`NOT`), and `anchor` pagination.
 
-### Error Handling
+## Error Handling
 
 `connect()` never throws; failures (unreachable host, wrong credentials, missing capabilities) are emitted as `error` events, and the instance holds no open sockets or timers afterwards. HTTP problem details (RFC 7807) and JMAP method-level errors are surfaced as `JmapError` with `httpStatus`, `problemType`, `problemDetail`, `jmapErrorType`, and `jmapErrorDescription` fields.
 

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/smartjmap',
-  version: '1.0.0',
-  description: 'A TypeScript JMAP client for reading, sending, and watching mail via the JSON Meta Application Protocol (RFC 8620/8621), with a bundled test server for offline testing.'
+  version: '2.0.0',
+  description: 'A TypeScript JMAP toolkit (RFC 8620/8621): an event-driven mail client for reading, sending, and watching mail, plus an embeddable JMAP server core with pluggable storage.'
 }

package/ts/classes.jmapclient.ts

@@ -140,6 +140,13 @@ export interface ISmartJmapMessage {
   raw: IJmapEmail;
 }
 
+/** An attachment reference for outgoing mail; upload the bytes first via `uploadBlob`. */
+export interface IJmapOutgoingAttachment {
+  blobId: string;
+  type: string;
+  name?: string;
+}
+
 export interface IJmapOutgoingEmail {
   /** Sender; defaults to the address of the account's first JMAP Identity. */
   from?: IJmapEmailAddress;
@@ -149,6 +156,8 @@ export interface IJmapOutgoingEmail {
   subject?: string;
   textBody?: string;
   htmlBody?: string;
+  /** Attachments referencing blobs previously uploaded with `uploadBlob`. */
+  attachments?: IJmapOutgoingAttachment[];
 }
 
 export interface IJmapSendResult {
@@ -156,6 +165,14 @@ export interface IJmapSendResult {
   submissionId: string;
 }
 
+/** The upload endpoint's response (RFC 8620 §6.1). */
+export interface IJmapUploadResult {
+  accountId: string;
+  blobId: string;
+  type: string;
+  size: number;
+}
+
 /** Error thrown for HTTP-level (RFC 7807 problem details) and JMAP method-level errors. */
 export class JmapError extends Error {
   public httpStatus?: number;
@@ -466,6 +483,14 @@ export class JmapClient extends plugins.events.EventEmitter {
     if (htmlBodyParts.length) {
       emailCreate.htmlBody = htmlBodyParts;
     }
+    if (outgoing.attachments?.length) {
+      emailCreate.attachments = outgoing.attachments.map((attachment) => ({
+        blobId: attachment.blobId,
+        type: attachment.type,
+        name: attachment.name ?? null,
+        disposition: 'attachment',
+      }));
+    }
 
     const responses = await this.request([
       ['Email/set', { accountId: this.accountId, create: { newEmail: emailCreate } }, 'c0'],
@@ -500,6 +525,39 @@ export class JmapClient extends plugins.events.EventEmitter {
     return { emailId: createdEmail.id, submissionId: createdSubmission.id };
   }
 
+  /**
+   * Uploads raw bytes to the session's uploadUrl (RFC 8620 §6.1) and returns
+   * the stored blob's id, type, and size. Use the blobId in
+   * `sendEmail({ attachments: [...] })` or any other blob reference.
+   */
+  public async uploadBlob(
+    data: Uint8Array,
+    type: string = 'application/octet-stream'
+  ): Promise<IJmapUploadResult> {
+    const template = this.session?.uploadUrl;
+    if (!template) {
+      throw new Error('JMAP session provides no uploadUrl — call connect() first.');
+    }
+    const expanded = template.replace('{accountId}', encodeURIComponent(this.accountId));
+    const url = new URL(expanded, this.config.sessionUrl).toString();
+    // Re-wrap so the bytes are backed by a plain ArrayBuffer (BodyInit-safe).
+    const body =
+      data.buffer instanceof ArrayBuffer ? (data as Uint8Array<ArrayBuffer>) : new Uint8Array(data);
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: {
+        authorization: this.getAuthHeader(),
+        'content-type': type,
+        accept: 'application/json',
+      },
+      body,
+    });
+    if (!response.ok) {
+      throw await this.createHttpError(response, 'Failed to upload blob');
+    }
+    return (await response.json()) as IJmapUploadResult;
+  }
+
   /**
    * Downloads a blob's raw bytes using the session downloadUrl template
    * (RFC 8620 §6.2: {accountId}, {blobId}, {type}, {name}).