@push.rocks/smartjmap 2.0.0 → 2.1.0

package/dist_ts/interfaces.backend.d.ts

@@ -111,6 +111,17 @@ export interface IJmapSubmissionInput {
     /** The raw RFC 5322 payload (the email's blob) — the backend performs the actual sending. */
     message: Uint8Array;
 }
+/**
+ * Authenticated, admitted upload handed to a streaming backend. The backend
+ * must reserve quota before reading `stream`, consume it through EOF, and
+ * abort its storage operation when `signal` fires.
+ */
+export interface IJmapBlobUploadStream {
+    stream: ReadableStream<Uint8Array>;
+    size: number;
+    type: string;
+    signal: AbortSignal;
+}
 /** Standard result shape for the /get-style backend reads. */
 export interface IJmapGetResult<T> {
     /** Backend-owned opaque state string for the collection at read time. */
@@ -311,6 +322,14 @@ export interface IJmapMailBackend {
         blobId: string;
         size: number;
     }>;
+    /**
+     * Optional streaming upload path. When present, JmapServer requires a valid
+     * Content-Length and never buffers the request before invoking this method.
+     */
+    uploadBlobStream?(accountId: string, upload: IJmapBlobUploadStream): Promise<{
+        blobId: string;
+        size: number;
+    }>;
     /** Returns a blob's bytes and metadata, or null when unknown. */
     getBlob(accountId: string, blobId: string): Promise<IJmapBlobRecord | null>;
     /** Returns the sending identities of the account with their collection state. */

package/dist_ts/interfaces.backend.js

@@ -10,4 +10,4 @@ export class JmapBackendError extends Error {
         this.name = 'JmapBackendError';
     }
 }
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW50ZXJmYWNlcy5iYWNrZW5kLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHMvaW50ZXJmYWNlcy5iYWNrZW5kLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQXdRQTs7OztHQUlHO0FBQ0gsTUFBTSxPQUFPLGdCQUFpQixTQUFRLEtBQUs7SUFDekMsWUFBbUIsSUFBWSxFQUFFLFdBQW9CO1FBQ25ELEtBQUssQ0FBQyxXQUFXLElBQUksSUFBSSxDQUFDLENBQUM7UUFEVixTQUFJLEdBQUosSUFBSSxDQUFRO1FBRTdCLElBQUksQ0FBQyxJQUFJLEdBQUcsa0JBQWtCLENBQUM7SUFDakMsQ0FBQztDQUNGIn0=
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW50ZXJmYWNlcy5iYWNrZW5kLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHMvaW50ZXJmYWNlcy5iYWNrZW5kLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQW9SQTs7OztHQUlHO0FBQ0gsTUFBTSxPQUFPLGdCQUFpQixTQUFRLEtBQUs7SUFDekMsWUFBbUIsSUFBWSxFQUFFLFdBQW9CO1FBQ25ELEtBQUssQ0FBQyxXQUFXLElBQUksSUFBSSxDQUFDLENBQUM7UUFEVixTQUFJLEdBQUosSUFBSSxDQUFRO1FBRTdCLElBQUksQ0FBQyxJQUFJLEdBQUcsa0JBQWtCLENBQUM7SUFDakMsQ0FBQztDQUNGIn0=

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@push.rocks/smartjmap",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "private": false,
   "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.",
   "exports": {
@@ -12,12 +12,11 @@
   "author": "Task Venture Capital GmbH <hello@task.vc>",
   "license": "MIT",
   "devDependencies": {
-    "@git.zone/tsbuild": "^4.4.0",
-    "@git.zone/tsrun": "^2.0.3",
-    "@git.zone/tstest": "^3.6.3",
-    "@types/node": "^25.6.0"
+    "@git.zone/tsbuild": "^4.4.2",
+    "@git.zone/tsrun": "^2.0.5",
+    "@git.zone/tstest": "^3.6.6",
+    "@types/node": "^26.1.1"
   },
-  "dependencies": {},
   "repository": {
     "type": "git",
     "url": "git+https://code.foss.global/push.rocks/smartjmap.git"

package/readme.md

@@ -4,10 +4,10 @@ A TypeScript JMAP toolkit (RFC 8620/8621): an event-driven mail client for readi
 
 ## 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`, `Request`/`Response`, and `ReadableStream` available in Node.js 18+ (and in Deno/Bun for the server core).
@@ -144,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
@@ -220,6 +228,17 @@ await jmapClient.disconnect();
 
 `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).
 
+Production consumers that rely on bounded streaming uploads can verify the
+server surface before starting a listener:
+
+```typescript
+import { JMAP_SERVER_STREAMING_API_VERSION } from '@push.rocks/smartjmap';
+
+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):
@@ -287,13 +306,19 @@ The `authenticate` option replaces the built-in Basic/Bearer registry entirely.
 import { JmapServer } from '@push.rocks/smartjmap';
 
 const jmapServer = new JmapServer({
+  authenticationChallenges: ['Bearer realm="jmap"'],
   authenticate: async (request: Request) => {
-    const token = request.headers.get('x-app-token');
+    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):
@@ -307,7 +332,7 @@ Implement `IJmapMailBackend` against your own store to serve real mail. All stat
 | `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 |
+| `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 |
@@ -325,9 +350,15 @@ const jmapServer = new JmapServer({
 
 `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, 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 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.
 

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/smartjmap',
-  version: '2.0.0',
+  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.'
 }