@push.rocks/smartjmap 1.0.0 → 2.1.0

package/readme.md

@@ -1,20 +1,23 @@
 # @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
 
-To install `@push.rocks/smartjmap`, use pnpm (or npm):
+Install `@push.rocks/smartjmap` with pnpm:
 
 ```sh
-pnpm install @push.rocks/smartjmap
+pnpm add @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 = {
@@ -141,8 +144,16 @@ const message = await jmapClient.getEmail(messages[0].id);
 // Convenience: set the $seen keyword
 await jmapClient.markSeen(message.id);
 
+// Mark unread, toggle flagged, move, or permanently destroy
+await jmapClient.markUnseen(message.id);
+await jmapClient.setFlagged(message.id, true);
+await jmapClient.setMailboxes(message.id, ['archive-mailbox-id']);
+
 // Replace the full keywords object
 await jmapClient.setKeywords(message.id, { $seen: true, $flagged: true });
+
+// Permanently destroy the email after any other mutations are complete
+await jmapClient.destroyEmail(message.id);
 ```
 
 ### Sending Mail
@@ -161,6 +172,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 +224,41 @@ 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).
 
-`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`.
+Production consumers that rely on bounded streaming uploads can verify the
+server surface before starting a listener:
 
 ```typescript
-import { JmapClient, JmapServer } from '@push.rocks/smartjmap';
+import { JMAP_SERVER_STREAMING_API_VERSION } from '@push.rocks/smartjmap';
 
-const jmapServer = new JmapServer();
+if (JMAP_SERVER_STREAMING_API_VERSION !== 1) {
+  throw new Error('This application requires smartjmap streaming server API v1.');
+}
+```
+
+### The Offline Test Server
+
+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, MemoryMailBackend } from '@push.rocks/smartjmap';
+
+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 +267,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 +277,96 @@ 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
+```
+
+### 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));
 ```
 
-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.
+`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({
+  authenticationChallenges: ['Bearer realm="jmap"'],
+  authenticate: async (request: Request) => {
+    const match = request.headers.get('authorization')?.match(/^Bearer\s+(.+)$/i);
+    const token = match?.[1];
+    return token === 'sesame' ? { username: 'appuser' } : null;
+  },
+});
+```
+
+Set `authenticationChallenges` to the exact schemes accepted by a custom
+authenticator. The built-in registry advertises both Bearer and Basic by
+default.
+
+### 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)` / optional `uploadBlobStream(accountId, upload)` / `getBlob(accountId, blobId)` | buffered or streaming 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.
+
+When `uploadBlobStream` is implemented, the server authenticates and admits the
+request before reading, requires `Content-Length`, and passes `stream`, exact
+`size`, media `type`, and an abort `signal`. The backend must consume exactly
+`size` bytes, reserve quota before reading the stream, reject short or oversized
+input, honor cancellation, and remove partial storage on failure.
+
+### 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, `maxConcurrentRequests` 4, and per-principal `maxConcurrentUpload` 4 — violations produce request-level `limit` errors, `requestTooLarge` method errors, or upload problem details. Constructor `limits` override advertised limits; `maxConcurrentUploadServer` adds a process-wide upload ceiling, and `mapUploadError` maps storage failures to application-specific RFC 7807 responses. `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.1.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.'
 }